get_skill_proposal

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description reinforces that with "Read-only." Beyond the annotations it adds real behavioral context: long file, annotation and source lists are paginated, and a cursor call returns only the next page. It stops short of page-size limits, ordering guarantees, or auth requirements, so it is strong but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the payload description, then usage, then the diff/pagination caveats, then args — a sensible order. The payload enumeration is dense and sprawling in one sentence, but each listed item (dismissal, archived-redirect target, verified evidence) conveys information an agent would otherwise have to guess. Slightly heavy, not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema and only two parameters, so the description carries the full burden of explaining the return shape — and it does so field by field, including the diff-dependent annotations and the paging contract. An agent can call this correctly and interpret the result without further context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description has to carry the parameters, and it does: proposal_id is sourced from list_skill_proposals with the prp_ prefix shown, and cursor is defined as next_cursor from a previous call, scoped to files, annotations and sources specifically. It also clarifies that annotation line numbers refer to the diff returned by get_skill_proposal_diff, which is genuine semantic value. Minor gap: no stated cursor default behavior (pass null/omit on first call).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ("Return one skill proposal") and immediately enumerates the payload: summary, target skills with written-against vs current version, agent brief, rationale, evidence, sources, revision history, dismissal, file changes, annotations, effects, flag finding, and Agent Inbox link. This is unmistakably distinct from list_skill_proposals and get_skill_proposal_diff, which are both named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the trigger explicitly: "Use when the user asks what a proposal says or why an agent proposed it." It also routes the agent to the right neighbors — the ID comes from list_skill_proposals (prp_…) and a single file's diff comes from get_skill_proposal_diff — so the boundary with both plausible alternatives is spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.