Moxie Docs

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description redundantly states 'Read-only; no side effects' but adds value by disclosing the return format ('Returns a single Markdown document') and the fallback behavior when the token serves multiple repos. No contradictions.

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?

The description is brief but packed with essential information: purpose, content list, safety, return type, and usage order. It is front-loaded with the core action and structured logically, with zero fluff.

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?

Given the simple parameter set (1 optional param), rich annotations, and no output schema, the description covers everything an agent needs: what it does, when to use it, what it returns, and how to handle the edge case of omitted repository. It is fully complete for its complexity.

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 100% and the property description fully explains the repository parameter, including case-insensitivity and the multi-repo fallback. The tool description repeats this information but does not add any new semantics beyond what the schema already provides, so the baseline score of 3 applies.

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?

The description clearly states the tool's purpose: it returns a compact briefing for pre-edit context, listing specific content (index status, commands, tips, etc.). It differentiates from siblings like get_conventions and get_doc_gaps by being a combined briefing, and it explicitly mentions get_doc_impact as a follow-up, showing awareness of sibling tools.

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?

The description gives explicit usage direction: 'Call this first at the start of a task' and instructs to follow up with get_doc_impact for path-scoped guidance. This provides clear when-to-use and an alternative, exceeding baseline expectations.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value by declaring no side effects and outlining the structured return content (method, path, request/response schema, known consumers/features), which is not fully available from any output schema.

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?

The description is three well-structured sentences: purpose, side-effect declaration, and usage timing. It is front-loaded with the most important information and contains no filler or redundant restating.

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 two-parameter, no-output-schema tool, the description covers the return payload, read-only nature, and when to invoke it. It could be slightly stronger by explaining fallback behavior when repository is omitted, but the schema already covers that, so the overall context is sufficient.

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 100%, so the baseline is 3; the schema already explains paths and repository semantics thoroughly, including multi-repo behavior. The description adds little beyond framing paths as files 'an agent is about to touch,' so no extra score is warranted.

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?

The description uses a specific verb ('return structured context') tied to a clear resource ('API endpoints') derived from file paths. It enumerates the returned fields (method, path, request/response schema, consumers/features) and distinguishes this from sibling tools by pairing it with get_doc_impact.

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?

The description explicitly says to call this tool before editing API route or schema code, and names get_doc_impact as a complementary tool. It does not provide a formal when-not-to-use exclusion, but the use case is clearly scoped to pre-edit API impact assessment.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Read-only; no side effects' earns no credit. What the description adds beyond structured data is the return shape (Markdown list grouped by category, with title, summary, confidence score, guidance and evidence paths), which is genuinely useful since no output schema exists.

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?

Three sentences, front-loaded with purpose before return details and routing guidance. Every sentence contributes, though 'Read-only; no side effects' is marginally redundant with the annotations.

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?

With no output schema, the description compensates by detailing the return format and fields; parameters are fully covered by the schema and safety by the annotations. Nothing an agent needs to call this correctly is 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 100%: both the optional category filter and the repository parameter are fully documented in the schema, including the multi-repo fallback behavior. The description adds no parameter syntax or format detail beyond this, so the baseline of 3 applies.

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 ('Get the coding conventions Moxie Docs inferred for the repository') and names the sibling it is not for path-scoped work (moxie.get_doc_impact). An agent can distinguish it from get_doc_impact and sibling context tools without opening a schema.

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?

Explicitly gives the when-to-use ('for the general rules to follow') and the when-to-prefer-an-alternative condition ('when you already know the files you're about to edit, prefer moxie.get_doc_impact'). The alternative and its selecting condition are both named.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds the return shape (Markdown list with title, severity, summary, suggested file paths), which matters since there is no output schema. It restates 'Read-only; no side effects' but adds genuine context beyond the annotations.

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?

Three sentences, front-loaded with purpose, then behavior/return, then routing. No filler; every sentence carries distinct information.

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?

With only two fully-documented parameters and no output schema, the description supplies the missing return-format detail and the routing rules, leaving no gap an agent needs to call this correctly.

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 100%, and the schema's repository field already documents the owner/name format and the multi-repo fallback behavior. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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 ('List the unresolved documentation gaps Moxie Docs found') and immediately scopes it ('areas of the codebase that lack docs'), which distinguishes it from sibling get_documentation_opportunities and get_doc_impact.

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?

Explicitly routes the agent: it declares 'This is gaps only' and names both alternatives with the condition that selects each ('for the full prioritized work queue... use get_documentation_opportunities', 'to scope gaps to files you're about to edit use get_doc_impact').

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so 'Read-only; no side effects' largely repeats structured data. The description does add genuinely new context – the Markdown report return format and the rule that a doc whose cited paths are all deleted becomes a removal candidate – which is useful, but not rich beyond that.

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 trigger condition, then the return payload, then the workflow routing. Every clause earns its place – no filler, no restating the name.

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?

No output schema exists, and the description compensates by itemizing what the report contains and its format. Combined with full parameter documentation and read-only annotations, an agent has everything needed to call it correctly.

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 100%, so the schema already documents repository, changedPaths, and deletedPaths fully. The description's mention of an 'optional subset being deleted' and path-based overlap adds framing but no syntax or format detail beyond the schema, so the baseline 3 applies.

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?

The description names a specific trigger (file paths an agent is about to change) and enumerates the concrete outputs: conventions, documentation gaps, related docs, net-new/undocumented analysis, and removal candidates. An agent can distinguish this from siblings like get_doc_gaps or get_conventions because it is path-scoped and aggregates several analyses.

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?

Explicit sequencing guidance: 'Call this BEFORE writing code so doc updates land in the same PR,' followed by named next steps (propose_doc_update to write, propose_doc_removal for orphans). Both the when and the alternatives are stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint/idempotent/non-destructive, so 'Read-only; no side effects' is largely redundant; the value-add is the disclosed return shape – a Markdown list with title, kind, severity, summary, suggested action, estimated files changed, and source paths. It does not mention auth scope or rate limits, but the safety profile is fully covered elsewhere.

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-loads what the tool returns, follows with the safety note, then the return structure, then the routing guidance. Every sentence carries distinct information; no filler.

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?

With no output schema, the description compensates by enumerating the returned fields in order. Combined with the read-only disclosure and sibling routing, an agent has everything needed to select and invoke it correctly.

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 100%, so kind, severity and repository are fully documented in the schema, including the important repository fallback behavior. The description adds no extra parameter semantics (e.g., filter combination rules), so baseline 3 applies.

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 ('List the actionable documentation updates Moxie Docs recommends as a prioritized queue') and enumerates the three content kinds it covers. It explicitly positions itself against the sibling get_doc_gaps ('the superset of get_doc_gaps'), so an agent can disambiguate without opening a schema.

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 a direct usage directive ('Use this to pick the next doc task') and names the alternative plus the condition that separates them (get_doc_gaps 'lists gaps only'). The superset framing tells the agent when this tool is the right choice over the narrower sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so 'Read-only; no side effects' is largely redundant. However the description adds the return shape (Markdown list with title, explanation, source citations), which the annotations do not convey. Useful added context, but partly overlapping with structured fields.

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?

Two tight sentences: the first states what it is, the second states usage and the alternative. Front-loaded and no filler.

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?

No output schema exists, and the description compensates by describing the return format. With annotations carrying the safety profile and schema covering the single parameter, nothing needed to invoke it correctly is 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 100% with a single parameter fully documented in the schema, including the multi-repo fallback behavior. The description adds no parameter detail, so the baseline 3 applies.

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+resource ('Get Moxie Docs' summary of how THIS repository organizes and maintains documentation') and scopes it to doc organization/placement. Clearly distinguishable from siblings like get_documentation_opportunities or list_docs.

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?

Explicitly states when to use it ('to decide WHERE a new doc should go before calling propose_doc_update') and names the alternative for a different question ('for the list of WHICH docs need work, use get_documentation_opportunities instead'). Both the trigger and the exclusion are spelled out.

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

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

With annotations already declaring read-only, idempotent, non-destructive, the description adds beyond them: it discloses the return format (Markdown grouped by section), fields included (title, slug, repository path, source paths), total count and pagination cursor, and explicitly promises no silent truncation. This is rich, annotation-complementing transparency.

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?

The description is front-loaded with the core purpose, then safety, then return details, then usage guidance. It is three sentences, each earning its place, no fluff or repetition of schema field names that are already self-explanatory.

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?

Given 4 optional params, rich annotations, and no output schema, the description covers the key operational behaviors: read-only guarantee, return structure, pagination honesty, repository fallback behavior, and when to use it versus siblings. It is complete for an agent to decide whether and how to call it.

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 coverage is 100%, so baseline is 3. The description adds contextual meaning beyond the schema: it explains the repository fallback behavior (returns repository list when omitted with multi-repo tokens) and mentions the cursor in the response for pagination. It doesn't elaborate on section filter syntax beyond what the schema gives, but the added behavior notes justify a 4.

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?

The description states a specific verb ('List') and resource ('repository's generated documentation'), and explicitly contrasts with a 'query-filtered subset' and sibling tool search_docs. It distinguishes itself from siblings by positioning itself as a full table of contents.

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?

The description gives explicit when-to-use guidance: use before adding a doc to avoid duplication, and to find slugs for propose_doc_update. It also states that search_docs is more direct for topic hunting, naming the alternative explicitly. This is exemplary usage guidance.

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

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

Goes well beyond the annotations by resolving the tension with destructiveHint=false: it explicitly explains that the tool only validates the path and returns it, does not delete files or open a PR, and that the actual deletion occurs in the caller's branch so it lands in the same PR. This is exactly the behavioral context an agent needs to act correctly on a mutation-shaped tool.

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-loads the core action and the critical 'what actually happens' clarification, and every sentence carries weight. The repeated 'Moxie Docs itself does not delete files or open a PR' phrasing is slightly verbose but the emphasis is warranted for a removal tool.

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, but the description supplies the return value ('the resolved path to delete') and explains the downstream consequence of the call. Combined with the branch/PR semantics, nothing essential for correct invocation is 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 coverage is 100%, so the schema already documents all five parameters, including the 'use instead of slug' note on targetPath. The description's 'Provide either slug or targetPath' lightly reinforces the mutual-exclusivity constraint but adds little beyond structured data, so the baseline 3 applies.

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 (propose deleting) and resource (Moxie Docs-tracked doc) and ties it to the caller's current change, which cleanly distinguishes it from the sibling moxie.propose_doc_update and the read-oriented get_* tools. An agent can identify the operation without opening the schema.

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?

It gives clear context for when to use it: when your change makes a doc irrelevant, as part of your current change, and it specifies slug-or-targetPath as the input choice. It stops short of explicitly naming propose_doc_update as the counterpart alternative or stating when removal is inappropriate, so it is strong but not fully explicit.

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

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

Goes beyond the annotations by disclosing that each call records a new non-idempotent proposal and that it does NOT modify the repository or open a PR, reconciling the tension with readOnlyHint=false. It also explains the resolution flow (Moxie resolves path, returns path + Markdown). Missing detail on rate limits or persistence lifetime.

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 core action and then the critical behavioral caveats. Mostly efficient, though the closing sentence about return values partially restates the preceding sentence's resolution flow.

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?

No output schema exists, so the description correctly describes the return (resolved target path and content). For a mutation-adjacent proposal tool with 7 params at 100% coverage, nothing essential to correct invocation is 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 coverage is 100%, so the baseline is 3, but the description adds real value by stating 'Provide either targetPath or baseSlug', a mutual-exclusivity rule the schema itself does not express. Other parameters are left entirely to the schema.

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 (propose) and resource (documentation file to add or update) and scopes it to the caller's current change. The contrast with the sibling propose_doc_removal is clear from the naming, and the description makes explicit that this is a proposal, not an actual write.

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 strong usage context: 'as part of YOUR current change' and the rationale that docs should land in the SAME PR as the code. It does not enumerate when-not to use or name alternatives, but the intended workflow is unambiguous.

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

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

Annotations already declare readOnlyHint/idempotentHint, but the description adds real value beyond them: the output shape (Markdown verdict of clean | warnings | must-fix), the per-finding structure (location, fix, doc slug), and the classification of findings by severity. It doesn't mention the 20-file cap or performance/rate characteristics, which keeps it short of a 5.

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?

Well front-loaded: the trigger (before PR) and the required input lead, then the return contract and next step follow. The second sentence is long with several stacked clauses, but every clause carries distinct information rather than filler.

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?

With no output schema and no annotations covering return values, the description carries that burden and does so: it specifies the verdict values, the per-finding fields, and the handoff slug for propose_doc_update. Combined with the explicit call-site ordering, an agent has everything needed to invoke and act on this tool.

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 coverage is 100%, so the schema already documents repository, changedFiles (path/patch/status/newContent), and deletedPaths in detail. The description reinforces the intent ('proposed new state of each changed file (and any deleted paths)') but adds no syntax, format, or constraint information beyond what the schema states, so the baseline 3 applies.

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?

The description names a specific verb and resource ('Self-review a change you are about to commit BEFORE opening the PR') and enumerates exactly what it detects: convention breaches, docs made false, undocumented net-new API surface, and broken references. It clearly differentiates from siblings by routing doc fixes onward to propose_doc_update rather than doing them itself.

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?

It states the exact timing ('Call this as the final step of the edit flow, then fix findings and re-run') and the triggering condition ('BEFORE opening the PR'), and it names the downstream alternative (propose_doc_update) with the artifact to hand it. Nothing about when to pick this over get_doc_impact or get_conventions is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Read-only; no side effects' is consistent with those. Beyond the annotations, it adds valuable behavioral context: results are 'ranked matches in Markdown grouped into Documentation and Code sections, each with a title, snippet, and source paths,' and omitting query returns recent context. This goes beyond the structured safety hints without fully covering all edge behaviors like pagination.

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?

Four sentences, front-loaded with the core purpose, then safety, then return format, then usage guidance. Every sentence carries unique information: scope, output structure, when-to-use alternatives, and edge-case behavior. No repetition or filler beyond a short safety reinforcement.

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?

Despite having no output schema, the description thoroughly explains return values (Markdown, grouped sections, title/snippet/source paths) and covers key invocation scenarios (open-ended lookup, omit query, specific getter alternatives). The rich schema covers parameter details and the annotations cover the safety profile, so nothing critical is left unexplained for a search tool.

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 100%, so all three parameters (limit, query, repository) are already documented with defaults, ranges, and fallback behaviors. The main description reinforces the query-omission behavior and result grouping but adds little parameter-level meaning beyond the schema, so the baseline 3 is appropriate.

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?

The description opens with a specific verb and scope: 'Keyword and semantic search across the connected repository's generated docs, conventions, documentation gaps, AI-context notes, and indexed code.' It clearly enumerates what is searched and differentiates from sibling getters by framing itself as the open-ended discovery tool, matching the annotation title 'Search docs and code.'

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?

Explicit guidance is provided: 'Use for open-ended lookups when you don't know which category holds the answer; when you do, the specific getters (get_conventions, get_doc_gaps, get_documentation_opportunities) are more direct.' It names concrete alternatives and also discloses the edge-case behavior of omitting query, giving the agent clear decision rules.

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