answer_context_gap

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

Annotations only say it is a non-read-only, non-destructive, non-idempotent write; the description goes far beyond that by disclosing the resulting state ('The gap then reads `answered`'), that the published Context 'stays unchanged until then', and the exact refusal conditions (a record that already has a waiting draft, a stale published_revision_number, a content_hash refused once the document changed). It also explains the proposal_id replay path, which is meaningful nuance given idempotentHint=false — conditional replay, not a contradiction.

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 purpose, then when-to-use, then source/draft rules, then an Args block — every section is findable. Mild redundancy: the prose paragraph already explains that every answer cites user_statements and kb_sources, and the Args block repeats the same definitions, so a few lines could be trimmed without losing meaning.

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?

For a nine-parameter mutation tool with no output schema and no annotation coverage of failure modes, the description supplies the state transition, the source-citation requirement, all refusal conditions, and the replay/idempotency escape hatch. Nothing an agent needs to call this correctly or recover from a refusal appears to be missing.

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 carries the full burden, and it documents all nine parameters, including provenance for each value ('gap_id from list_context_gaps', 'project_id from list_projects()', 'content_hash kb_get_document returned'). It adds genuine semantics beyond types: `body` is the record's whole text in Markdown, `published_revision_number` is null for a `missing` gap, and `replace_draft_number` must come from an earlier 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?

States a specific verb and resource ('Save the answer to ... a Context gap as a draft of the Context record the gap is about') and names the concrete example (Audience › Ideal customer profile). It immediately distinguishes itself from the publishing step by saying the draft 'waits on the project's Context page, where the consultant publishes or discards it'.

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?

Gives explicit trigger context ('Use when the user answers a gap's question, for example while going through list_context_gaps with them') and an explicit scope exclusion ('This tool doesn't publish, discard or delete'), which routes the agent away from the publish/discard tools. It does not explicitly contrast with the sibling propose_context_record, so the alternative-selection guidance is not fully closed.

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