# chatctx agent instructions

Use this as a policy block in an agent's system prompt, `AGENTS.md`, or tool-selection rules.

## What chatctx is

chatctx is a read-only MCP server that returns human-reviewed engineering guidance. It does not
generate code or answers. Every record is approved by an owner and carries source links.

- Endpoint: `https://chatctx-mcp.brackket.workers.dev/mcp`
- Tools: `search_knowledge`, `get_guidance`, `submit_feedback`
- Contract: `https://chatctx.pages.dev/api.json`

## When to call it

Call `search_knowledge` **before** deciding:

- a framework-specific practice (React, Next.js, TypeScript, PostgreSQL, Cloudflare)
- a security control (input validation, authentication, secrets, SQL injection)
- an accessibility pattern (landmarks, focus management, contrast, images)
- a testing, reliability, or performance strategy
- a code review judgement about established practice

Call `get_guidance` **after** a search hit when you need exceptions, pitfalls, verification checks,
or version constraints before acting.

Call `submit_feedback` **after** a call when the result was unhelpful, incorrect, outdated, or
missing. This is the only way the owner learns about retrieval gaps.

## When not to call it

- For general conversation, code generation, or refactoring mechanics.
- For secrets, credentials, customer data, or private source code. Send only a short task
  description and optional stack metadata.
- For facts outside the reviewed engineering corpus. The service will return `no_match`; do not
  reinterpret that as an answer.
- For write operations. There are none.

## How to call it

1. `initialize`, then `notifications/initialized`.
2. Send `Accept: application/json, text/event-stream`, or the server returns `406`.
3. Phrase `query` as the decision being made, not as keywords alone.
4. Pass `technologies` and `versions` when you know them; it improves applicability ranking.
5. Keep `max_results` small (2–5) and raise `token_budget` only when you need more text.

## How to read the response

- `retrieval.mode: "hybrid"` — normal.
- `retrieval.mode: "keyword_fallback"` — embeddings were unavailable; recall is lower.
- `retrieval.mode: "no_match"` — nothing relevant. Tell the user, or broaden and retry once.
- `retrieval.degraded: true` — treat recall as reduced and say so if it matters.
- `retrieval.technology_filter_fallback: true` — your technology filters were too narrow.
- `retrieval.truncated: true` — the token budget cut results; raise it or narrow the query.

Always read `applies_to`, `conditions`, and `exceptions` before applying a recommendation. Similarity
is a retrieval signal, not proof of applicability. Cite the returned `sources` when you use the
guidance.

## Output rules

- Prefer the record's `recommendation` and `verification_checks` over your own recollection.
- If guidance conflicts with the user's constraints, surface the conflict instead of silently
  choosing one.
- If the service returns `no_match`, say the knowledge base has no reviewed guidance for it. Do not
  invent a record, slug, or source.
- Never present `submit_feedback` as a way to publish or change content.

## Failure handling

| Status | Meaning | Do |
| --- | --- | --- |
| `401` | bad or revoked key | stop retrying, report the credential problem |
| `403` | wrong host | use the documented endpoint |
| `406` | missing `Accept` | add `application/json, text/event-stream` |
| `429` | quota exhausted | wait for `Retry-After`, then retry once |

On a tool-level `isError: true` result, read `error.code` and `error.message`. Do not retry
validation errors with the same arguments.