amicus 0.7.0__tar.gz → 0.8.0__tar.gz

{amicus-0.7.0 → amicus-0.8.0}/.agents/skills/agent-friendly-mcp/SKILL.md

@@ -4,7 +4,7 @@ metadata:
     github-path: agent-friendly-mcp
     github-ref: refs/heads/main
     github-repo: https://github.com/briandconnelly/skills
-    github-tree-sha: ebf496f66a9bc542464fdea730466f40080a4dd6
+    github-tree-sha: 9cd3ae57ef60ea4338ef777c4983aad4e2225a07
 name: agent-friendly-mcp
 ---
 # Agent-Friendly MCP
@@ -32,7 +32,7 @@ Read the cited ids — a row names the concern but does not define the rule, so
 
 | Concern | Governing rules |
 | --- | --- |
-| What carries the contract, and what is only advisory | `[5.scaffolding-only]`, `[5.ap-contract-container]`, `[2.instructions-advisory]` |
+| What carries the contract, and what is only advisory | `[5.scaffolding-only]`, `[5.ap-contract-container]`, `[2.instructions-advisory]`, `[2.instructions-prefix]`, `[2.truncation-signal]` |
 | Capability negotiation before optional features | `[1.negotiated-caps]` |
 | Tool granularity: tasks vs endpoints | `[3.task-completing]`, `[3.hide-steps]`, `[3.ap-endpoint-wrapping]` |
 | Side effects, idempotency, and rate limits | `[3.declare-effects]`, `[3.honest-annotations]`, `[3.annotation-defaults]` |

amicus-0.8.0/.agents/skills/agent-friendly-mcp/decisions/006-instructions-prefix.md

@@ -0,0 +1,51 @@
+# 006 — Server `instructions` delivered as a prefix
+
+Decided 2026-09-26.
+Triggered by issue #184, which reported that Claude Code delivers only a fixed-length prefix of a server's `instructions` string and proposed rules for laying the string out around that cut.
+
+## Question
+
+`[2.instructions-advisory]` covered a client that never surfaces `instructions`.
+It did not cover a client that surfaces the head and drops the rest, which leaves the agent holding a plausible partial contract.
+Which rules does that failure need, and should the skill state a length budget?
+
+## Evidence
+
+These are dated observations of client behavior, not protocol facts.
+Each figure can change with a client release, and at least one is configurable per session.
+
+| Client | Observation | Source |
+| --- | --- | --- |
+| Claude Code | First 2,048 characters of a 13.9 KB string reached the model, followed by a client-rendered `… [truncated]` marker; earlier readings on the same client landed near 2,041 bytes and 2,058 characters. | Issue #184, citing runpod/snowpod#463, #437, #299 (2026-09-26 and earlier) |
+| Claude Code 2.1.283 | A fresh session's transcript records the injected block (an `mcp_instructions_delta` attachment): exactly the first 2,048 characters of amicus 0.7.0's 3,438-character instructions, matching the server's `manifest_snapshot.all.json` fixture, followed by `… [truncated]`. That prefix holds two em dashes, so it is 2,052 UTF-8 bytes: the cut is in characters, not bytes. The block arrived with the session's second message, when the slow-starting server finished connecting; on the first message neither amicus's tools nor its instructions were present, so the model said it saw none. `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` was unset in the authoring session, which saw the same 2,046 visible characters. | The maintainer's session `d7a2e144`, 2026-09-26, and this PR's authoring session, both read against the amicus fixture |
+| Claude Code (changelog) | 2.1.280 "Added `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` to change the 2,048-character cap on MCP tool descriptions and server instructions for every MCP server in the session." The cap is a documented default the user can raise or lower, so a server cannot know the prefix a given Claude Code session delivers. | <https://code.claude.com/docs/en/changelog.md>, read 2026-09-26 |
+| Codex CLI 0.157.1 | Codex carries the full `instructions` string inside the server's tool descriptions. In a VS Code-hosted session, amicus 0.6.0's 3,392-character (3,396-byte) string, byte-identical to its `initialize` result, heads a 6,030-character `amicus_backends` description, and the four amicus descriptions visible in a separate, truncated capture begin with the same text. No separate instructions text was reported: fresh `codex exec` sessions told not to use tools said they saw none, and one listing its tools listed no MCP tools. `codex exec` sessions prompted to find a tool definition recovered the whole string, including an 11,682-character ASCII probe (last sentinel and tail value correct); the transcripts do not show whether that text sat in starting tool metadata or arrived through an unlogged lookup. No cut was seen at these lengths, including none at 1,000 bytes for a plugin-declared server, and the lengths are lower bounds. A fresh VS Code-hosted TUI session told not to use tools also reported no amicus server instructions, only the amicus skill listing; its rollout shows no tool calls and does not contain the instructions text. Other Codex surfaces were not measured. | The maintainer's sessions and this PR's probes, 2026-09-26, read from the Codex session rollouts and debug log |
+| Codex (docs) | "Keep the first 512 characters self-contained so the most important guidance is available when Codex is deciding how to use the server." No truncation limit is documented. | <https://learn.chatgpt.com/docs/extend/mcp?surface=cli> and <https://developers.openai.com/plugins/build/mcp-server>, read 2026-09-26 |
+
+Issue #184 also reported a cold-start observation (runpod/snowpod#462): with a truncation self-test at the head, the agent followed the rules inside the prefix and went straight to the resource it needed, without acting on the self-test.
+
+## Decision
+
+Add two rules and extend one.
+
+- `[2.instructions-advisory]` names the prefix case and the tool-definition case (Codex CLI above) alongside the never-surfaced case, so all three route to the same "never the sole carrier" requirement.
+- `[2.instructions-prefix]` owns the layout and the length budget.
+- `[2.truncation-signal]` owns the self-check the agent can run on its own copy, and why it is a floor (the cold-start observation above).
+- `review-workflow.md` gains a measurement step in the cold-start probe and a Major example for binding rules past a measured prefix.
+
+The rules state no number.
+The two measured clients fail differently: Claude Code cuts at a user-adjustable 2,048 characters, while Codex CLI carried at least 5.7× that uncut, inside tool definitions rather than as separate context.
+The documented Codex figure is guidance rather than a limit.
+A skill meant for many clients would be wrong for most of them if it bound one client's figure.
+The figures live in this record so a reader can see where a budget came from and when it was last measured.
+
+## Rejected
+
+A fixed 2,048-character budget in the rule, as issue #184 proposed.
+It is one client's current behavior; applied to Codex CLI it would cap a server's usable text at under a fifth of what that path carries in its tool definitions, and it is not stable even within Claude Code, where a session can change it.
+
+A separate rule for digests over glossaries (issue #184's proposed `2.instructions-digest-not-glossary`).
+It is one consequence of ordering by what the agent needs first, so it lives as a sentence in `[2.instructions-prefix]` rather than as a third rule with its own id.
+
+Measuring in both characters and UTF-8 bytes until the unit is known, as the issue proposed.
+The Claude Code measurement above settles the unit for that client, and the rule already asks for the unit each target client cuts in, which covers clients whose unit is still unknown.

{amicus-0.7.0 → amicus-0.8.0}/.agents/skills/agent-friendly-mcp/references/contract-checklist.md

@@ -99,10 +99,22 @@ Audit prompt: Can an agent learn what this server does, what it doesn't, and whi
   The optional `instructions` field rides this result under 2026-07-28 — it is no longer carried by an `initialize` response — and remains advisory wherever it travels (`[2.instructions-advisory]`).
   Say in the capability summary how an agent gets from `server/discover` to the house surfaces, because a capability advertisement does not carry the task-level guidance `[2.summary]` requires.
 
-- `[2.instructions-advisory]` **Treat server `instructions` as advisory, never as the sole carrier.** Some clients never surface the `instructions` field to the model, so behavior that exists only there is invisible to those agents.
+- `[2.instructions-advisory]` **Treat server `instructions` as advisory, never as the sole carrier.** Some clients never surface the `instructions` field to the model, some surface only a prefix of it (`[2.instructions-prefix]`), and some carry it only inside the server's tool definitions rather than as separate context, so behavior that exists only there is invisible to those agents, or visible only where the agent reads those definitions.
   Essential selection, prerequisite, safety, and repair behavior must also reach the agent through a surface it is guaranteed to see — the tool and resource schemas, or a discovery tool or resource the client does honor.
   Using `instructions` is fine; relying on it alone is not.
 
+- `[2.instructions-prefix]` **Lay out `instructions` so the prefix a client delivers is still a correct contract.** Some clients deliver only a fixed-length prefix of `instructions` and drop the rest; whether the agent sees any marker of the cut is up to the client, so an agent holding a partial copy can proceed as though it had the whole contract.
+  Order the text by what the agent needs before its first call: negative scope, binding safety and ordering rules, and the pointer to the full contract come first; material comes after only when another surface already puts it in front of the agent before its first call — tool routing that `tools/list` carries qualifies on a client that preloads the catalog, not on a host that withholds definitions until selection (`[2.pd-host]`).
+  Spend the head on branch rules, not glossaries: a payload that describes itself when it arrives, such as an error envelope, needs only which field to branch on, which value means do not retry, and where the full glossary lives.
+  Prefix lengths are client properties, often undocumented, and free to change between releases or even between sessions, so no single figure binds: keep the binding contract inside the shortest prefix measured on the clients you target, measured in the unit each client cuts in, and date where each figure came from (the observations on record live in `decisions/006-instructions-prefix.md`).
+  A target with no measurement, or a session whose configuration may have changed its cut, gets no claim that its prefix holds the binding contract; for that target the other carriers `[2.instructions-advisory]` requires and the check in `[2.truncation-signal]` are the protection.
+  A length test is evidence only when its limit comes from such a measurement; one that asserts an unmeasured limit stays green while the client cuts the text.
+
+- `[2.truncation-signal]` **Give the agent a check it can run on its own copy of `instructions`.** "Clients may truncate" is not a rule under `[2.rules-then-context]`: it names no condition an agent can evaluate, because the agent cannot tell whether its copy was cut.
+  State at the head the exact line the text ends with and what to read when the agent's copy does not end with it, and pin that line last with a test so a reorder cannot break the check silently.
+  Name a line, not a section: a cut inside the final section leaves its heading visible and passes a section-presence check.
+  The check is a floor, not a substitute for `[2.instructions-prefix]`: in the one cold-start observation on record the agent followed the rules inside the prefix and never acted on the check, so the directives themselves must sit inside the prefix.
+
 - `[2.negative-scope]` **State negative scope explicitly.** What the server does NOT do is as important as what it does.
   Negative scope prevents wasted exploration and wrong-tool selection.
 

{amicus-0.7.0 → amicus-0.8.0}/.agents/skills/agent-friendly-mcp/references/design-workflow.md

@@ -93,7 +93,7 @@ Decide how an agent finds the right primitive at the lowest cost its clients all
 
 - Write the server capability summary: what it does, what it does NOT do, and any prerequisites that affect whether or how an agent should use it.
 - Expose the summary through a resource, discovery tool, or instructions field, whichever the client honors.
-  Treat `instructions` as supplemental because some clients do not surface it to the model.
+  Treat `instructions` as supplemental (`[2.instructions-advisory]`) and lay it out under `[2.instructions-prefix]` and `[2.truncation-signal]`.
 - Make compact definitions your baseline (§2), then, if you need progressive disclosure, pick a mechanism by cost axis: host-managed context disclosure, server-managed catalog disclosure, or client-independent surface reduction — only the last helps a client that preloads and never lazy-loads.
 - Make discovery selective, but through a discovery tool, resource catalog, or authorization-scoped catalog — native `tools/list` takes only a pagination cursor and has no filter parameters.
   A flat list of 80 tools is undiscoverable.

{amicus-0.7.0 → amicus-0.8.0}/.agents/skills/agent-friendly-mcp/references/review-workflow.md

@@ -19,7 +19,7 @@ Step 1's calibration for a missing capability summary is the worked model; apply
   Without that, an imprecise auth error is a repair-quality defect and lands in Major: it costs turns without establishing a security risk or a reliable task failure.
   Blocks merge.
 - **Major** — agent will frequently choose the wrong primitive, waste tokens, or hit avoidable errors.
-  Examples: overlapping tool descriptions, bloated definitions or a 50-tool catalog with no client-independent surface reduction (and no progressive-disclosure mechanism matched to the target clients), unstructured error strings with no symbolic codes, no capability fingerprint for a target client that caches or pins the server surface, resource lists that inline bodies.
+  Examples: overlapping tool descriptions, bloated definitions or a 50-tool catalog with no client-independent surface reduction (and no progressive-disclosure mechanism matched to the target clients), unstructured error strings with no symbolic codes, binding `instructions` rules that sit past a target client's measured prefix and reach the agent through no other surface, no capability fingerprint for a target client that caches or pins the server surface, resource lists that inline bodies.
 - **Minor** — degrades agent experience but recoverable.
   Examples: verbose default responses with no detail toggle, missing `request_id` correlation, ambiguous parameter names whose schema types still constrain shape, summaries longer than three sentences.
 - **Nit** — style, naming, or doc improvement.
@@ -61,6 +61,8 @@ Each should be answerable from concrete evidence — schema text, response paylo
 - **Cold start.** What does an agent see when it first connects?
   Can it learn what the server does, what it does NOT do, and what prerequisites affect use in one read?
   Trace the first few definition loads from a transcript or simulate them from the schema. *(maps to §1, §2)*
+  When the server sets `instructions`, render the string it actually sends and measure it: total length, the offset where each section ends, and which sections fall past the prefix measured on each target client (`[2.instructions-prefix]`).
+  Where you can run a target client, place sentinels at known offsets and ask a fresh session which ones it can see, then confirm from the session's transcript whether the answer came from its starting context, a tool lookup, or a file read, and record the provenance as unresolved when the transcript does not show it; otherwise record the prefix check as `not-checked` for that client, in the §2 row's notes of the coverage table, rather than borrowing another client's figure.
 - **Tool selection.** Given two adjacent tools (same verb, overlapping nouns, or similar surface), can an agent pick the right one without invoking both?
   Are descriptions narrow enough that the schema alone disambiguates?
   Look for tools whose descriptions you cannot tell apart at a glance. *(maps to §3; see `examples.md` §10 for the failure-mode shape)*

{amicus-0.7.0 → amicus-0.8.0}/.agents/skills/agent-friendly-mcp/tests/rule-ids.txt

@@ -20,6 +20,8 @@
 2.summary
 2.discover-first
 2.instructions-advisory
+2.instructions-prefix
+2.truncation-signal
 2.negative-scope
 2.rules-then-context
 2.compact-baseline