Moxie Docs

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

Annotations already declare readOnly and idempotent hints; the description reinforces 'Read-only; no side effects.' It adds value by stating the return format ('Returns a single Markdown document') and the special behavior when the repository parameter is omitted (returns list of repos). No contradiction 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?

Four concise sentences: purpose, behavior, output, and usage guidance. Front-loaded with the most important information, each sentence contributes new information without redundancy.

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 adequately explains the return type (Markdown document) and the content scope. It covers edge cases (omitted parameter, multi-repo tokens) and provides a clear workflow with sibling tool. For a low-complexity read-only tool, this is complete.

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 thoroughly explains the repository parameter including format, case-insensitivity, and omitted behavior. The description adds no extra parameter semantics beyond what the schema provides, so 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 clearly states the tool's purpose: 'Get the compact briefing an agent should read before editing this repository' and enumerates the contents. It distinguishes itself from siblings by aggregating multiple categories (index status, commands, tips, conventions, gaps, opportunities) and explicitly names a follow-up tool (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 instructs 'Call this first at the start of a task' and provides a conditional follow-up: 'once you know which files you'll change, follow up with get_doc_impact for path-scoped guidance.' This clearly answers when to use this tool versus alternatives.

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. The description reinforces this with 'Read-only; no side effects' and adds behavioral context about mapping file paths to endpoints and what is returned. It does not contradict annotations, and it explains the tool's role in an edit workflow, which goes beyond the annotation flags.

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 tight: two sentences cover purpose, output, safety, and usage. Each clause earns its place, with the main purpose front-loaded and no filler or redundancy.

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 tool has no output schema, the description fills the gap by listing the output components (method, path, request/response schema, consumers/features). It also covers when-to-call and safety. However, it does not specify behavior for edge cases like no matching endpoints or invalid paths, which would make it fully complete.

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?

Input schema covers 100% of parameters with descriptions, so the baseline is 3. The main description adds context that paths are for files the agent is 'about to touch', but this is minor semantic enrichment beyond the schema's own descriptions. No additional format or syntax details are provided.

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 a specific verb ('return structured context') and resource ('API endpoints') mapped from file paths, with concrete output details (method, path, schema, consumers/features). It distinguishes itself from sibling tools by focusing on API endpoint context, not general AI or documentation.

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 an explicit when-to-use directive: 'Call this before editing API route or schema code, alongside get_doc_impact.' It names a complementary sibling tool but does not provide when-not-to-use guidance or alternative tool comparisons. Clear context, but not exhaustive exclusions.

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?

The description discloses read-only, no-side-effects behavior, the full return shape (Markdown list grouped by category, with title, summary, confidence score, agent guidance, and evidence file paths), and the fallback behavior when repository is omitted. It adds meaningful context beyond the annotations without contradicting them.

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 compact and front-loaded: it states the verb and resource first, then safety, return format, and usage guidance in a few sentences. Every sentence earns its place, with no fluff or repetition of structured fields.

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 fully explains what the tool returns, how results are structured, and what each convention item contains. It also covers when to use it versus alternatives and the repository-omission behavior, making the tool feel complete for an agent to select and invoke.

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 both parameters thoroughly. The description adds some context by mentioning example categories and the multi-repository fallback behavior, but it does not substantially extend parameter semantics beyond what the input schema already provides.

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 resource: 'Get the coding conventions Moxie inferred for the repository.' It then explains the output format and explicitly distinguishes this tool from moxie.get_doc_impact, making the purpose unambiguous and well differentiated from siblings.

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 guidance: 'Use this for the general rules to follow; when you already know the files you're about to edit, prefer moxie.get_doc_impact...' This clearly states when to use the tool and when to choose an alternative. It also provides practical invocation guidance about the repository parameter behavior.

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?

The description explicitly mentions 'Read-only; no side effects,' and details the output format ('Returns a Markdown list...'). It also notes the limitation that only gaps are included. This goes beyond the annotations (which already indicate read-only) by adding behavior specifics, making the tool's behavior fully transparent.

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 concise yet comprehensive, using two sentences to convey the purpose, output, and distinctions from related tools. It avoids redundancy and is well-organized.

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 tool's complexity (with alternative tools and conditional parameter behavior), the description provides all necessary context: what it does, what it returns, when to use alternatives, and how parameters affect behavior. No critical information 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?

The schema descriptions for both parameters are extensive (severity filter and repository with detailed instructions). The tool description does not add additional meaning beyond the schema, so the baseline score of 3 applies since coverage is 100%.

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 that the tool lists unresolved documentation gaps found by Moxie, with specific details about the output (title, severity, suggested file paths) and distinguishes it from related tools by explicitly stating 'gaps only' and recommending alternatives for other scopes.

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 provides explicit guidance on when to use this tool versus alternatives: 'for the full prioritized work queue... use get_documentation_opportunities' and 'to scope gaps to files... use get_doc_impact.' It also outlines parameter behavior (e.g., repository omission returns a list of repositories) and notes the read-only nature.

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 provide read-only and idempotent hints; description reinforces with 'Read-only; no side effects.' Adds value by specifying return type ('Markdown report') and content, going beyond annotations without contradicting them.

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 sentences, front-loaded with the core purpose. Slightly verbose in listing report contents, but each element adds clarity. Could be tightened, but structure is logical and scannable.

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?

Without an output schema, the description adequately enumerates report sections (conventions, gaps, related docs, net-new analysis, removal candidates). Sufficient for a complex tool with multiple siblings.

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 has 100% coverage with detailed descriptions for all parameters. The tool description adds minimal new information beyond rephrasing ('file paths an agent is about to change' vs schema's 'intends to modify'). Baseline 3 is appropriate given high schema coverage.

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?

Clearly states the tool analyzes file paths to return conventions, documentation gaps, related docs, net-new/undocumented analysis, and removal candidates. Distinguishes from siblings by mentioning 'before writing code' and directing to propose_doc_update/removal.

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 instructs when to call ('BEFORE writing code') and provides workflow context with alternatives ('then use propose_doc_update... or propose_doc_removal'). Gives clear contextual usage.

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?

The description states 'Read-only; no side effects,' which aligns with and reinforces the annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true). It also discloses the return format (Markdown list) and the detailed composition of the items. The behavior around repository scope (returning list of repositories when omitted and token is multi-repo) is disclosed in the repository parameter description, not in the main body, but the main description conveys the core no-side-effect trait.

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 tightly-scoped sentences. The first states purpose and behavior; the second gives the return composition, usage guidance, and sibling distinction. No filler or redundancy.

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 that there is no output schema, the description compensates by listing the fields of the returned Markdown items (title, kind, severity, summary, suggested action, estimated files changed, source paths). It is not missing critical behavioral details for a read-only listing tool. Slight gap: it does not explicitly state that results are returned in priority order despite calling it a 'prioritized queue' in the first clause, but this is fairly clearly implied.

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% — all three parameters (kind, severity, repository) have descriptions in the schema. The description adds the crucial behavioral context for the repository parameter: 'If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer.' This meaningfully goes beyond a simple schema definition.

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 it lists actionable documentation updates in a prioritized queue: missing docs, drift repairs, and PR-template work. It distinguishes itself from sibling get_doc_gaps by explicitly naming it as a subset ('it is the superset of get_doc_gaps').

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 'Use this to pick the next doc task' and identifies the alternative tool to use instead for gaps-only ('get_doc_gaps'). This provides clear when-to-use guidance and names the sibling alternative.

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, destructiveHint=false. The description adds 'Read-only; no side effects' reinforcing annotations, and goes beyond by specifying the return format (Markdown list of pattern entries) and the edge-case behavior when repository is omitted (returns list of repos). This adds value beyond annotations without contradicting them.

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 in the first sentence, then side effects, then usage guidance and alternative. No fluff; every sentence earns its place.

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 tool with one optional parameter and no output schema, the description fully covers what it does, when to use it, and how to choose alternatives. The return format is described, so it's complete for the agent to decide when to call.

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 already explains the 'repository' parameter thoroughly (when to omit, result of omission, case-insensitivity). The description adds no new parameter details, 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?

The description clearly states the verb 'Get' with a specific resource ('Moxie's summary of documentation patterns') and explicitly differentiates from siblings by naming get_documentation_opportunities for a different purpose. It says exactly what it returns: a list of pattern entries with title, explanation, and citations.

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 ('before calling propose_doc_update') and when not to ('for the list of WHICH docs need work, use get_documentation_opportunities instead'). This directly addresses tool selection and is very clear.

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?

Description discloses read-only nature, no side effects, pagination behavior (no silent truncation), and return format (Markdown grouped by section, entries, count, cursor). Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so description adds value by explaining return format and pagination guarantee.

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?

Description is a single sentence block, but it's dense and informative. It front-loads the purpose, then adds behavior, return details, and usage guidance. Slightly long but each phrase contributes value; no waste.

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, 100% schema coverage, no output schema, and rich annotations, the description sufficiently covers what the tool does, return structure, pagination, and when to use it. It could mention whether result is sorted or how sections are defined, but it's complete enough for a listing 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% with detailed parameter descriptions. Description adds a bit of context for repository (multi-repo behavior) and section, but params are already well-explained in schema. Baseline 3 is appropriate; description does not add significant new meaning beyond what schema provides, though it reiterates pagination cursor.

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?

Purpose is explicit: 'List the repository's generated documentation as a browsable table of contents' — specific verb (list) + resource (generated documentation) + scope (every doc page, not query-filtered). Clearly distinguishes from search_docs and propose_doc_update.

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?

Provides explicit usage guidance: 'Use this to see what docs already exist before adding one... or to find the slug to pass to propose_doc_update; when you are hunting for a specific topic, search_docs is more direct.' This tells when to use and when not to use, naming alternatives.

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?

Beyond the annotations (destructiveHint=false), the description explicitly states that Moxie does not delete files or open a PR, and that the deletion happens in the user's branch. This clarifies the non-destructive nature and the return of a resolved path, which is more detailed than annotations alone.

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 concise sentences that front-load the purpose and immediately state the key caveat (no actual deletion). Every sentence adds unique information without redundancy.

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?

The description covers the workflow, side effects, return value, and parameter alternatives. With no output schema, it mentions the return type. The schema handles individual parameter details, making the description complete for selection and invocation.

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?

The schema already covers 100% of parameters with descriptions. The description adds the important either/or relationship between slug and targetPath, which is not in the schema and guides parameter selection.

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 specific action: propose deleting a Moxie-tracked documentation file made irrelevant by the current change. It distinguishes itself from siblings like propose_doc_update (update vs removal) and the read-only get_* tools by emphasizing the proposal and deletion context.

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 clearly indicates when to use: when your change makes a doc irrelevant and you want the deletion to land in the same PR. It implicitly contrasts with propose_doc_update, but doesn't explicitly name alternatives or exclusions.

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 annotations by explicitly stating it is not idempotent, does not modify the repo or open a PR, and returns content to write. This discloses side effects clearly, aligning with readOnlyHint=false, idempotentHint=false, and destructiveHint=false.

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?

One dense paragraph, but front-loaded with purpose and includes essential behavior. Could be broken into bullets but is not overly verbose or repetitive. Every sentence adds value.

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 explicitly mentions it 'Returns the resolved target path and the content to write', covers the non-idempotent nature, and explains the repository omission behavior. Sufficient for the agent to use 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 covers all 7 parameters at 100%, but the description adds crucial semantics: 'Provide either targetPath or baseSlug' clarifies the mutual exclusivity not present in the schema. It also echoes repository behavior, but that's already in 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?

The description clearly states the tool proposes a documentation file to add or update, using specific verb and resource. It distinguishes from siblings by explicitly noting it does NOT modify the repository or open a PR, contrasting with propose_doc_removal and read-only get 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 clear context: use as part of the current change to add or update docs in the same PR. It doesn't explicitly state when not to use it or mention alternatives, but the 'does NOT modify...' phrasing implies when it's appropriate. The repository parameter guidance further clarifies usage conditions.

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?

The description adds behavioral detail beyond the annotations: it states 'Read-only; no side effects and no writes' and explains that it returns a severity-ranked list and a Markdown verdict with location and fix info. It also reveals that it can list available repositories if repository is omitted, which is a behavioral quirk. Annotations already declare readOnlyHint: true, destructiveHint: false, so the description reinforces and adds specifics about output format and the repo listing behavior. This is more than baseline, so a 4 is appropriate, though it could also mention any rate limits or other constraints but that's not necessary.

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 well-structured, starting with the primary action and context ('Self-review a change...'), then the input requirements, then the output format, then the usage instruction. It is comprehensive yet concise, using bullet points implicitly. It front-loads the purpose and constraints, and every sentence adds value. It's a bit long but appropriate for the complexity. No 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 tool's complexity (multiple parameters, output description, side effects-free), the description is complete. It explains the input, output format, the process, and the usage flow. It also handles edge cases like repository scoping and deleted paths. Even without an output schema, it clearly describes the Markdown verdict and its contents. The description fully compensates for any lack of structured output information. For a tool with such detailed documentation, this is a top score.

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?

The description explains the key parameter 'changedFiles' by saying 'Pass the proposed new state of each changed file (and any deleted paths)' and that it returns findings. However, the input schema already covers parameters comprehensively with descriptions at 100% coverage. The description does clarify that 'changedFiles' should be in proposed new state, and mentions max 20 files per call, which is additional detail. It also explains how deletedPaths work. Since the schema is thorough and the description supplements with usage context, a 4 is justified. It doesn't describe the 'repository' parameter in depth but the schema does; the description's instruction about repository missing behavior is useful but not essential.

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: 'Self-review a change you are about to commit BEFORE opening the PR.' It specifies the verb ('review'), resource ('change'), and actionable scope (pre-PR commit step). It also distinguishes from siblings by emphasizing 'read-only' and 'no side effects' and the review of violations. Sibling tools like get_doc_impact or list_docs are read-only but not for pre-commit self-review, so it is differentiated.

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 'Call this as the final step of the edit flow, then fix findings and re-run.' This gives clear when-to-use guidance. It also mentions that it should be used before opening a PR, and implies it's for editing content. While it doesn't explicitly say when NOT to use it, the final-step instruction and the highlighted purpose are sufficient for usage guidance. It also contrasts with siblings by implying other read tools (like get_conventions or get_doc_gaps) are for gathering context, not reviewing changes. Overall, this is strong 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?

Annotations already provide readOnly, idempotent, and non-destructive hints, so the bar is lower. The description adds valuable behavioral detail beyond annotations: Markdown output, Documentation/Code grouping, ranked matches with titles, snippets, and source paths, plus the recent-context fallback. No contradiction with annotations 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 dense, well-ordered sentences cover scope, output behavior, and usage guidance without fluff. The description is front-loaded with the core purpose and keeps every sentence useful.

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?

Combined with complete schema coverage and strong annotations, the description supplies purpose, when-to-use guidance, output shape, and fallback behavior. It compensates well for the lack of an output schema, making the tool easy to select and invoke 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 baseline is 3. The description reinforces parameter context, especially around query omission, but mostly repeats what the schema already states rather than adding materially new parameter-level semantics.

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?

Clearly identifies a keyword and semantic search tool across docs, conventions, gaps, AI-context notes, and indexed code. It distinguishes itself from sibling getters by positioning search as the open-ended option and naming more direct category-specific alternatives.

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 search vs. the specific getters, saying to use it for open-ended lookups when the target category is unknown. It also documents the omit-query behavior for returning recent context, giving clear invocation guidance.

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