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

Annotations only set readOnlyHint=false and idempotentHint=false, but description adds important behavioral context: 'Append-only' (non-destructive, no updates) and constraints like 'maxItems: 20' for reasonCodes. However, doesn't detail what happens on duplicate submissions or error behavior.

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 gives usage guidance and parameter semantics in a structured way. While comprehensive, it could be slightly more concise 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 tool with 7 parameters (4 required, arrays, enums) and an output schema, the description covers the purpose, usage constraints, parameter roles, semantics, and behavioral traits. It leaves no significant gaps for an agent to use the tool 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 has 0% description coverage, but the description compensates by explaining grade semantics ('full = helped complete the task, partial = somewhat useful but flawed, no = wrong or wasted the turn') and listing starter reason codes for each grade. It also explains referencedToolName and referencedRequestId, but misses projectId and projectRef fields.

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 as an 'append-only feedback tool for rating a prior Mako tool run from the agent perspective'. It distinguishes itself from the sibling 'agent_feedback_report' by being the writing tool.

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 advises to 'Use sparingly when a result was notably good, notably bad, or wrong; do not emit routine feedback after every call', providing clear when-to-use and when-not-to-use criteria. Also specifies that it 'Requires referencedToolName and referencedRequestId so each row is tied to a specific prior run'.

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 that the tool is read-only (consistent with annotation), returns grade counts and bounded recent entries, and is filterable, adding useful behavioral 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?

Two sentences efficiently convey the tool's purpose and usage, with no wasted words and a clear, front-loaded structure.

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 output schema exists but the description omits many parameters and does not mention pagination or sorting, leaving significant gaps for a tool with 7 parameters and 0% schema coverage.

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?

Despite 0% schema description coverage, the description only mentions 'referencedToolName, grade, and ISO time window', missing many parameters like projectId, projectRef, and limit, leaving meaning unclear.

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 returns grade counts and recent entries for agent feedback, with specific mention of filtering by tool name, grade, and time window, distinguishing it from the sibling 'agent_feedback' tool.

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 suggests using the tool to review which tools agents found helpful, noisy, wrong, or incomplete, providing clear use context but lacking explicit exclusion or alternative tools.

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 mark destructiveHint=true and idempotentHint=false. The description adds behavioral context: hunks must apply cleanly with exact context, clarifying the strict matching requirement. No contradiction with 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?

Two succinct sentences with no filler. Every sentence conveys essential information: what it does and a critical constraint. Ideal structure for quick agent comprehension.

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 one parameter and an output schema not shown, the description covers the key behavioral constraint (exact context). It could mention that this mutates files (implied by destructiveHint) but is mostly complete. No mention of error behavior, but that may be in the output schema.

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 a detailed parameter description for 'diff' specifying format and file headers. The tool description adds no additional semantic value beyond the schema, so a baseline of 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 applies a multi-file unified diff and specifies the requirement for exact context matching. The name 'apply_patch' is self-explanatory and distinguishes it from siblings like 'file_edit' or 'file_write' which handle single file modifications.

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 does not provide explicit guidance on when to use this tool versus alternatives (e.g., file_edit for single files, shell_run for custom patches). It implies usage for applying diffs but lacks when-not-to or alternative tool references.

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 readOnlyHint=true, so no contradiction. The description adds the 'conservatively fall back' behavior, which provides some transparency beyond annotations, but overall adds limited behavioral context.

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 a single, concise sentence that immediately conveys the tool's purpose. It is well front-loaded with no wasted words.

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 complexity of a router tool and the presence of many sibling tools, the description is minimal. It does not explain what 'canonical named tool' means or provide enough context for an agent to use it effectively, though an output schema may exist.

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%, and the description does not explain the parameters (question, projectId, projectRef). It adds no meaning beyond the schema, failing to compensate for the lack of parameter descriptions.

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 is a router tool that maps a natural-language engineering question to a canonical named tool or falls back to free_form. It distinguishes from sibling tools that are not routers.

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 implies when to use (when you have a question that might map to a tool) and mentions the conservative fallback to free_form. However, it does not explicitly state when not to use it or list alternative tools.

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 readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description adds substantial behavioral context: it never edits files (read-only), explains the retry logic for ambiguous TSX/JSX snippets with auto-anchored parser context, describes the reef-backed freshness guard to avoid phantom matches, and mentions the MAKO_REEF_BACKED environment variable for rollback. No contradictions with 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?

The description is relatively long but front-loaded with the core purpose. Each sentence adds value, covering purpose, retry logic, freshness guard, and usage guidance. No fluff, but could be slightly more structured (e.g., separate sections). Overall efficient for the amount of 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?

Given 9 parameters with 0% schema coverage, the description explains key behavioral traits (retry, freshness, safety) and return values. However, it does not detail all parameters or provide output schema details (though output schema exists externally). For a moderate-complexity tool, it covers the most important aspects but leaves some gaps, such as parameter documentation and error conditions.

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 must compensate. It explains the 'pattern' parameter (ast-grep pattern), mentions 'captures' (captured metavariables), and implies 'languages' by listing file types. However, other parameters like projectId, projectRef, pathGlob, maxMatches, maxFiles, and excludeAcknowledgedCategory are not explained. The description adds partial value but is insufficient for all 9 parameters.

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 is a code-intelligence tool for structural pattern search using ast-grep, specifies the file types (TypeScript/TSX/JavaScript/JSX), and lists the return value (typed matches: file, line range, column range, matched text, captured metavariables). It effectively distinguishes itself from text/FTS search by labeling it as structural pattern search.

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 use it when text/FTS search is too noisy for structural queries, with concrete examples like console.log($X) and await supabase.rpc($NAME). It does not explicitly exclude scenarios, but the 'use when' guidance is clear and helpful. It also mentions retry behavior for ambiguous TSX/JSX snippets, providing context for when the tool automatically adjusts.

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 readOnlyHint and idempotentHint, so the description adds value by disclosing the 'without overclaiming' philosophy and the specific fallback behavior (matched:false with suggestedNext). It does not contradict annotations. Minor gaps: unclear behavior when multiple parameters are provided.

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 purpose, no wasted words. Efficient and easy to parse.

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 an output schema present, the description doesn't need to detail returns, but it does cover the fallback. However, given 5 optional parameters and sibling tools, more context on parameter interactions and when to choose this over other tools would improve completeness.

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 must compensate. It mentions only three of five parameters (route, file, feature) with no details on their meaning or constraints. missing semantics for projectId and projectRef.

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 is an 'Answer tool for auth questions' that 'trace likely auth boundaries for a route, file, or feature', specifying the verb and resources. It also distinguishes itself from sibling tools like cross_search by describing the fallback behavior of returning matched:false with a suggestedNext for cross_search instead of throwing.

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 tells when to use (for auth questions about a route, file, or feature) and implies when not (if no exact match, use cross_search). It also mentions that the tool's non-throwing behavior is beneficial for batches and agent workflows. However, it does not explicitly exclude other sibling tools like route_trace.

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 are present (readOnlyHint=false, idempotentHint=false, openWorldHint=true) and the description adds behavioral context: it runs external executables, persists ProjectFinding rows, and records run status (unavailable/error/succeeded). This goes beyond annotations without 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?

The description is reasonably concise and starts with a clear purpose statement. It packs several details (executable, reporter, persistence, status tracking) without excessive verbosity. Minor improvement could be breaking parameter-related content into a clearer structure.

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 5 parameters, 0% schema description coverage, and existence of an output schema (not shown), the description covers the main workflow but lacks detail on parameter specifics and the output format. It is adequate but not comprehensive for a tool with side effects and multiple inputs.

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%, yet the description only implicitly relates parameters: 'files' are mentioned as 'project-relative files', 'scriptName' is hinted but not explicitly explained. Parameters like 'projectId', 'projectRef', and 'maxFindings' are not described at all. The description fails to add sufficient semantic meaning for the majority of parameters.

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 action ('run', 'persist', 'record'), the resource ('Biome diagnostics', 'files'), and the specific behavior (uses `check --reporter=gitlab`, persists ProjectFinding rows under source 'biome'). It distinguishes from siblings like eslint_diagnostics by specifying 'Biome' and 'GitLab-reporter package script'.

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 guidance by stating 'File-mode only' and 'deliberately avoids Biome's experimental JSON reporter', implying it is for deterministic file-by-file checking. However, it does not explicitly mention when to use this tool over sibling diagnostic tools (e.g., eslint_diagnostics) or provide conditions for avoidance.

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 and idempotentHint=true. Description adds context about 'bounded change scope' and 'path-derived' computation but no deeper behavioral details beyond what annotations imply.

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?

Single sentence, 14 words, no fluff. However, conciseness sacrifices completeness given tool complexity.

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 8 parameters, nested objects, enums, and a large sibling set, the description is too brief. It does not explain key terms like 'direct surfaces' or 'one-hop dependent surfaces', and omits any guidance on required parameters or typical use.

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 0%, but the description does not explain any parameters. Parameters like startEntity, targetEntity, direction, traversalDepth have no additional meaning provided. The description fails to clarify the complex nested object parameters.

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 returns 'path-derived direct surfaces, one-hop dependent surfaces, and an explicit dependency order' for bounded change scope. It is specific but does not explicitly differentiate from sibling tools like graph_path or flow_map.

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?

No guidance on when to use this tool versus alternatives (e.g., graph_neighbors, graph_path). No exclusions or context for appropriate 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds value by stating the tool is read-only, does not refresh the index, uses deterministic providers, exposes retrieval diagnostics, and mentions a rollback path. No contradictions with 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?

The description front-loads the core purpose and adds necessary technical details. Sentences are dense but each adds value. Could be slightly more concise, but overall efficient for a complex 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?

The description provides a thorough explanation of the tool's role, behavior, and outputs (retrieval diagnostics, enrichments). However, it lacks detail on most input parameters and does not leverage the existing output schema to reduce the burden. Adequate for high-level understanding but incomplete for precise 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?

Schema description coverage is 0% and the description only mentions one parameter (risksMinConfidence) explicitly. With 17 parameters, the description fails to compensate for the lack of schema-level parameter documentation, leaving most inputs unexplained.

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 defines the tool as a first-mile context scout for coding agents, using deterministic providers to produce ranked, source-labeled context. It distinguishes itself from siblings by stating its role before normal harness loops, making the purpose highly specific and unambiguous.

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 says 'Use as the first-mile packet before normal harness read/search/edit loops', providing clear usage context. However, it does not specify when to avoid this tool or mention alternative tools for different scenarios, leaving some gap.

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 key behavioral information beyond annotations: it errors if the file already exists. Annotations already provide readOnlyHint=false and destructiveHint=true, and the description aligns with these. It does not mention other behaviors like permission requirements or return value, but the presence of an output schema and annotations reduces the burden.

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 primary action, then error condition and alternative. Every word earns its place with no 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's simplicity (2 required params, no enums, no nested objects), the description covers the essential purpose, error condition, and alternative. Annotations and output schema fill remaining gaps, making it 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 coverage is 100%, so both parameters have descriptions in the input schema. The description adds no additional meaning to the parameters beyond what is already in the schema. Baseline score of 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 verb 'create' and resource 'file at a project-relative path', and distinguishes it from the sibling tool file_write by noting that it errors if the file already exists and to use file_write to overwrite. This provides a specific and distinguishable purpose.

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 states when to use this tool (to create a new file) and when not to (if file already exists, use file_write). This provides clear guidance on alternatives and 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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds useful behavioral nuance about exact literals routing to a bounded preview, which goes beyond 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?

Two sentences, each serving a distinct purpose: defining scope and providing usage alternatives. No redundant or unnecessary text.

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 a good purpose statement and usage guidelines, the lack of parameter descriptions leaves gaps in completeness. The tool has 5 parameters with no explanation of how verbosity or limit affect results, or the role of projectId/projectRef.

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?

With 0% schema description coverage, the description fails to explain any of the 5 parameters (term, limit, projectId, verbosity, projectRef). The agent must rely solely on the schema for parameter meaning, which is insufficient.

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 searches across multiple resource types (code chunks, schema objects, RPC/trigger bodies, routes, stored memories) and distinguishes from the sibling tool live_text_search, providing a specific verb and resource set.

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 advises when to use live_text_search instead (full inventories, regex, custom glob scope), giving clear context and alternatives for the agent.

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 confirms read-only nature and mentions pg_catalog, but adds little beyond annotations which already include readOnlyHint, idempotentHint, and openWorldHint. No additional behavioral traits disclosed.

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?

Single sentence, front-loaded with key purpose information. No fluff, every word 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?

With 4 undocumented parameters and many sibling tools, the description is insufficient for an agent to correctly select and invoke the tool. Output schema exists but does not mitigate parameter gaps.

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% and description provides no information about parameters (projectId, projectRef, table, schema). The description does not compensate for missing schema descriptions.

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?

Description clearly states read-only tool for inspecting columns and primary-key details via pg_catalog, using specific verbs and differentiating from sibling tools like db_table_schema and db_fk.

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?

Description implies use for column questions but does not explicitly state when to use versus alternatives or provide exclusions. It lacks concrete guidance on context.

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 openWorldHint. The description adds the method 'via pg_catalog' and the scope of inspection, enhancing transparency 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?

The description is a single concise sentence that front-loads the key information ('Read-only database tool for relationship questions'), with no wasted words.

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?

While the purpose is clear and annotations cover behavioral aspects, the description omits explanations for projectId and projectRef parameters, which are needed for complete context in a 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?

With 0% schema description coverage, the description does not explain any of the four parameters (projectId, projectRef, table, schema). It only implies the 'table' parameter by mentioning 'for a table', leaving others undocumented.

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 'inspect' and clearly identifies the resource as 'inbound and outbound foreign-key references for a table', distinguishing it from sibling tools like db_columns or db_table_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 states the tool is for 'relationship questions', providing clear context for when to use it, but does not explicitly mention when not to use it or suggest alternative tools.

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 openWorldHint. The description adds behavioral details about what data is surfaced (platform, version, schemas, transaction state), going beyond the annotation hints.

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 a single concise sentence that efficiently conveys the tool's purpose and scope without extraneous 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?

The description, combined with annotations and the presence of an output schema, covers the core behavior. However, the lack of parameter explanation leaves a notable gap in completeness for a tool with two required-looking parameters.

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 has 0% description coverage for its two parameters (projectId, projectRef). The description offers no explanation of what these parameters represent or how they affect the call, leaving the agent without necessary context to provide correct values.

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?

Description clearly states it is a read-only database tool for verifying connectivity and surfacing platform, version, schemas, and transaction state. This is a specific verb-resource pair that distinguishes it from sibling tools like db_columns or db_table_schema which have more specific functions.

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 implies usage for initial connectivity checks and metadata retrieval, but does not explicitly state when to use it versus other database-related sibling tools, nor does it provide exclusions or prerequisites.

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 indicate read/write and non-idempotent behavior. The description confirms mutation by stating 'replace indexed Reef facts'. It also discloses dependency on existing snapshot. However, it could be more explicit about failure modes if snapshot is missing.

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, no unnecessary words. First sentence delivers the core purpose, second provides critical prerequisite. Front-loaded and efficient.

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?

While the output schema exists (so return values need not be explained), the description lacks parameter coverage. For a 6-parameter tool, the description should detail at least the key parameters to be 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?

With 0% schema description coverage, the description must compensate but only mentions a few aspects (snapshot, facts) and does not explain any of the 6 parameters (freshen, projectId, factsLimit, etc.). Users cannot infer parameter meanings from the description.

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 (replace/index) and resource (Reef facts), listing many specific components. It distinguishes itself from sibling tools like project_index_refresh by explicitly mentioning it uses an existing snapshot and that the sibling should be run first if stale.

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 this tool (for ingestion after snapshot is ready) and when to use the alternative (run project_index_refresh first if stale). This provides clear context for choosing among siblings.

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 indicate readOnlyHint=false, idempotentHint=false, and the description adds valuable context: 'append-only', writes to 'Mako's local project store', and 'never mutates the live database'. This is clear and helpful, though it could mention whether it can delete or modify existing comments.

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 a single, well-structured sentence that front-loads the purpose. It is concise, but could be expanded to cover key parameters without becoming verbose.

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 complexity (13 parameters, 3 enums, 0% schema description coverage) and presence of an output schema, the description covers behavioral transparency well but fails to document parameter semantics, leaving significant gaps for an agent to correctly invoke the 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 0%, so the description must explain parameters. It only mentions database object types but does not explain any of the 13 parameters (e.g., projectId, preview, category, severity, tags). The agent must infer meaning from parameter names and enums, which is insufficient.

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 is an 'append-only DB review note tool' for leaving comments on database objects, and explicitly lists supported object types. It distinguishes from siblings by emphasizing it writes only to local store, unlike potential sibling tools that might read or mutate the live database.

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 implies usage for leaving comments on database objects and highlights it never mutates the live database, but it does not explicitly contrast with sibling tools like db_review_comments (for reading). No when-not or alternative guidance is provided.

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 indicate readOnlyHint=true and idempotentHint=true. The description adds behavioral context by specifying 'Read' and 'append-only ledger', reinforcing the read-only nature and providing details about the data source (local, persistent, append-only). 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?

Two concise sentences: first describes function and filters, second gives usage context. No extraneous information. 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 11 parameters, 0 required, and an output schema present, the description covers the core use case but does not detail all filter options or relationships between parameters. Missing mention of projectId/projectRef, which are likely needed for scoping. Could be more comprehensive.

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 must compensate. The description lists major filter categories (object, category, tag, query, fingerprint) but omits projectId, projectRef, schemaName, parentObjectName, and limit. Only provides partial parameter meaning beyond 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 'Read DB review comments from Mako's local append-only ledger' with specific filtering options (database object, category, tag, free-text query, target fingerprint). It distinguishes from sibling tool 'db_review_comment' by indicating this is a read/browse operation rather than a single comment operation.

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 to 'Use during schema/table/RLS/replication review to recover prior AI/operator notes.' Provides clear context for when to use, but does not mention when not to use or alternative tools like db_review_comment.

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 readOnlyHint and idempotentHint; the description reinforces read-only nature and adds context about inspecting RLS state via pg_catalog, without 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?

A single, concise sentence front-loads the key purpose with no superfluous words.

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 an output schema present and a focused inspection task, the description covers the main purpose. However, lack of parameter detail slightly reduces completeness.

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 0% and the description only mentions 'table', leaving projectId, projectRef, and schema unexplained. This is insufficient given the low baseline 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?

The description clearly states the tool is for inspecting row-level security state and policies via pg_catalog, using specific verb 'inspect' and resource 'security questions'. It distinguishes itself from sibling database tools like db_columns and db_fk.

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 implies usage for security questions but does not provide explicit guidance on when not to use or alternatives among sibling tools.

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 states read-only, matching annotations, and adds that it returns signatures, return shape, language, and security, which goes beyond annotation hints. It also describes two modes of operation.

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?

Single sentence is concise and front-loaded with the core purpose. No waste, though could benefit from clearer separation of modes.

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?

Covers main usage modes and mentions return shape, language, security, but lacks explanation of many parameters. Output schema exists but not detailed. Adequate but with gaps.

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?

Only 'name' and 'list' are explained in the description, leaving 7 other parameters (e.g., limit, schema, argTypes) completely undocumented. With 0% schema description coverage, this is insufficient.

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?

Description explicitly states the tool inspects stored procedure/function signatures or enumerates routines, with specific verb 'inspect' and 'enumerate'. This clearly distinguishes it from siblings like rpc_neighborhood and trace_rpc.

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?

Clearly implies usage for function questions (inspecting signatures or listing routines), but does not explicitly exclude other cases or mention alternatives. Context is clear enough for an agent.

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 openWorldHint. The description adds scope (full table shape) but no additional behavioral traits beyond what annotations provide, so it meets the baseline.

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 a single sentence that front-loads the key concept ('Read-only database tool') and lists details efficiently without extraneous wording.

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 an output schema existing, the description lacks parameter guidance and usage context for a tool with four parameters (one required) and no parameter descriptions. It is incomplete relative to the tool's 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 0% and the description does not explain any parameter meanings. Parameter names (projectId, projectRef) are not self-explanatory, and the description fails to compensate for the lack of schema descriptions.

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 'Read-only database tool for full table shape' and lists specific aspects (columns, indexes, constraints, foreign keys, RLS, triggers), which distinguishes it from more focused sibling tools like db_columns or db_rls.

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 implies a comprehensive schema inspection tool, but does not explicitly state when to use versus alternatives like db_columns or db_rls. Context from sibling names provides some guidance, but no explicit when-not-to-use statements.

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 destructiveHint: true. Description adds valuable behavior: 'Snapshot captures the bytes for undo', indicating the deletion is potentially reversible. 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?

Two short, front-loaded sentences with no wasted words. Essential information is presented efficiently.

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 simple 1-param destructive tool with an output schema, the description covers the primary action and undo behavior. Missing info on error handling (e.g., file not found) but acceptable for this 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 coverage is 100% and already documents 'path' with its description. The tool description adds no additional semantic meaning beyond the schema, so baseline score 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?

Description clearly states the verb 'Delete' and the resource 'file at a project-relative path'. It is specific and distinct from sibling tools like create_file or file_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?

The description provides no guidance on when to use this tool versus alternatives (e.g., file_edit or other deletion methods). No when-not-to-use or prerequisites mentioned.

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 indicate a mutating operation (readOnlyHint=false, idempotentHint=false). The description confirms this: 'this is a mutation tool because it refreshes Reef state.' It also adds context about file-mode skipping and persistence, which goes beyond the annotations. No 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?

The description is two sentences, concise, and front-loaded with the action. It wastes no words but could be slightly more structured (e.g., separating conditions). Still effective.

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 complexity (9 parameters, nested objects) and presence of an output schema, the description covers the core purpose and a key condition (file-mode skipping). However, it lacks details about output format or parameter usage, making it adequate but not comprehensive.

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?

With 0% schema description coverage and 9 parameters, the description provides no explanation for parameters like projectId, maxFindings, or tsconfigPath. It only references 'sources' and 'files' briefly. This is insufficient for an agent to understand parameter roles.

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 invokes selected diagnostic sources and persists findings, returning a summary. It lists the exact sources (lint_files, programmatic_findings, etc.) and distinguishes itself from individual diagnostic tools by being an aggregation runner. This is specific and actionable.

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 implicitly says when to use this tool (for refreshing multiple diagnostic sources) but does not explicitly guide when not to use it or suggest alternatives like single-source tools. The note about file-mode sources is useful but incomplete.

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 indicate readOnlyHint=false and openWorldHint=true, and the description adds that the tool persists ProjectFinding rows, records run statuses, and operates only on specified files. This provides useful behavioral context beyond annotations, though details about side effects (e.g., overwriting previous findings) are missing.

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 a single, well-structured sentence that front-loads the main purpose and adds crucial constraints. Every clause serves a purpose, with no wasted words.

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 5 parameters with no schema descriptions and an output schema (not shown), the description covers core behavior but lacks parameter guidance. For a tool with side-effects and multiple sibling diagnostics, more parameter context would improve completeness.

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%, yet the description only mentions 'project-relative files' and does not explain parameters like projectId, projectRef, scriptName, or maxFindings. The description adds minimal meaning beyond the schema's names and types.

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?

Description clearly states it is an ESLint diagnostics ingestion tool that runs local ESLint on specific files, persists findings, and records run status. It distinguishes from broad-project lint tools by stating 'File-mode only; does not run broad project lint.' However, it does not explicitly differentiate from sibling diagnostic tools like biome_diagnostics or oxlint_diagnostics.

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 implies usage for specific project-relative files and notes it does not run broad project lint, giving context for when to use. However, it does not explicitly mention when not to use this tool or suggest alternatives, leaving the agent to infer.

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 says 'label facts and findings', implying a write operation, but annotations declare readOnlyHint=true, creating a direct contradiction. No additional behavioral context is provided 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?

Single sentence but somewhat verbose with domain jargon ('Reef 10 evidence-confidence view'). Could be more concise 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?

Despite having an output schema, the description does not specify what the tool returns. It covers the labeling intent but omits details on parameter usage, side effects, or output format.

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 0% and the description does not explain any of the 5 parameters. No value is added beyond the 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 the tool labels facts and findings with specific confidence levels, distinguishing its function as an evidence-confidence viewer. However, it does not explicitly differentiate from the sibling tool 'evidence_conflicts'.

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?

No guidance on when to use this tool versus alternatives like 'evidence_conflicts'. The description implies usage for labeling evidence but lacks explicit context or when-not cases.

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 indicate read-only and idempotent behavior. The description adds value by mentioning 'surfacing' (retrieval) and 'suggested cross-check actions' (actionable output), beyond what annotations provide. No 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?

The description is a single concise sentence that front-loads the key concept. However, the jargon 'Reef 10 conflict view' may reduce accessibility. Still, it is efficient with no wasted words.

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 6 parameters with no descriptions and an output schema, the description fails to explain parameter roles or output structure. It lacks sufficient detail for an AI agent to use the tool correctly without extra inference.

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 must compensate but does not mention any parameters by name or purpose. The meaning of projectId, projectRef, filePath, etc. is left entirely to the schema names and constraints.

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 surfaces stale evidence, conflict facts, and contradictory findings, with cross-check actions. It uses specific verbs and resources, and distinguishes from similar siblings like evidence_confidence.

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 implies use for viewing conflicts but does not explicitly state when to use this tool vs alternatives, nor does it provide exclusionary conditions or prerequisites.

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 and idempotentHint. The description adds the behavioral nuance of 'indexed' symbols, indicating that only indexed exports are listed, which is valuable 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?

The description is a single concise sentence that front-loads the core purpose. It is efficient, though it could expand slightly without becoming verbose.

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 three parameters and an output schema, the description fails to explain how to use the parameters (e.g., that 'file' is required) or what the output contains. The agent lacks essential context for correct 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 input schema has 0% description coverage and the tool description does not mention any parameters, their purposes, or how they relate to the function, leaving the agent with no guidance.

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 the specific verb 'list' and clearly identifies the resource as 'indexed symbols that a file exports'. It distinguishes this tool from the sibling 'symbols_of' by narrowing to exports only.

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 implies the tool should be used when needing a file's exported symbols, but it does not explicitly state when not to use it or suggest alternative tools like 'symbols_of' for all symbols.

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 openWorldHint. The description adds 'Does not write files or mutate Reef state' and explains the specific mining behavior, providing context beyond 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?

The description is a single, well-structured sentence that front-loads the purpose ('Read-only Reef rule-pack mining tool') and packs in key details without redundancy. Every word 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?

Given the tool's complexity (8 parameters, output schema exists), the description covers core inputs and outputs. However, it lacks context on prerequisites (e.g., project setup) and what 'related durable findings' entails. Almost 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 0%, so the description must compensate. It mentions 'git fix diff' (implying fixCommit, baseCommit, filePath) and 'YAML templates' (relating to output), but does not systematically explain all 8 parameters. Partial compensation but not complete.

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: 'inspect a local git fix diff and propose .mako/rules YAML templates from removed TS/JS anti-pattern shapes'. It uses specific verbs and resources, and distinguishes from siblings like file editors or database 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 implies usage for rule mining from diffs but does not explicitly state when to use this tool over alternatives like `reef_scout` or `reef_diff_impact`. No guidance on when not to use or how it compares to siblings.

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 indicate destructiveHint=true, covering the primary behavioral trait. The description adds no extra context about permissions, backups, or error cases, so it does not go 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?

Two sentences, front-loaded with the purpose, no wasted words. Efficient and easy to parse.

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 an output schema exists and annotations cover safety, the description fully explains the core behavior and the key constraint (unique occurrence) without needing elaboration on returns or side effects.

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 clear parameter descriptions. The tool description does not add additional meaning beyond what the schema already provides, meeting the baseline.

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 replaces a substring in an existing file, with a specific verb and resource. It distinguishes from siblings like create_file, delete_file, or apply_patch, which have different purposes.

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 provides a clear constraint (substring must occur exactly once unless replaceAll is true) but does not explicitly mention when to use this tool over alternatives like file_write or apply_patch.

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 and idempotentHint. The description adds value by explaining it computes a file subject fingerprint and returns facts across overlays, providing behavioral context beyond the annotations. 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?

Two sentences, front-loaded with purpose, no wasted words. Perfectly concise.

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?

An output schema exists, so return values need not be explained. However, with 8 parameters and no parameter descriptions in either schema or description, the tool is incomplete for proper use. The description covers purpose and behavior but omits essential parameter guidance.

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 provides no parameter details despite having 8 parameters with 0% schema description coverage. It mentions 'overlays' but does not explain the overlay parameter or any other required/optional parameters, forcing reliance on the bare 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 it is a read tool for one file's durable facts, computes a file subject fingerprint, and returns specific facts like working_tree_overlay file_snapshot rows. It is specific about verb and resource, but does not differentiate from sibling tools like file_findings or file_health.

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 says 'Use this to inspect what Reef currently knows about a file across overlays,' providing clear context for usage. However, it does not discuss when not to use this tool or mention alternatives among the many sibling tools.

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 readOnlyHint and idempotentHint. Description adds that findings are durable, uses same overlay/source/status filters as project_findings, and supports source aliases. 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?

Two concise sentences, front-loaded with purpose, no unnecessary words or repetition.

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 9-parameter complexity and existence of output schema, the description provides sufficient context for understanding the tool's purpose and usage. Could be enhanced by mentioning the return value characteristics, but output schema compensates.

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?

Despite 0% schema description coverage, the description mentions 'overlay/source/status filters' and 'source aliases', which adds semantic context. However, it does not individually describe the 9 parameters beyond a high-level mapping, leaving some clarity gaps.

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 returns 'durable Reef findings' for one file, identifies it as a read tool, and distinguishes it from sibling project_findings by specifying the same filters and source aliases.

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 says 'Use this before editing a file when a shell or agent needs known active diagnostics without rerunning broad lint.' Provides clear when-to-use context but does not elaborate on when not to use or explicitly name alternatives beyond project_findings.

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 and idempotentHint, so the safety profile is clear. The description adds that it summarizes with evidence, but does not disclose potential costs or depth of analysis 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?

Single sentence is concise and front-loaded with 'Answer tool for file questions'. Could be slightly more structured to separate input and output expectations.

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 3 parameters and no schema descriptions, the description is insufficient. It omits parameter explanations and does not clarify what 'evidence' means, making the tool harder to use 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 0%, so the description must explain parameters. It does not mention projectId, projectRef, or file at all, leaving agents to infer their meaning from context.

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 summarizes a file's role, dependents, and notable risks with evidence. It distinguishes from sibling tools like file_facts or file_findings by focusing on a holistic summary, though it could be more explicit about what 'evidence' entails.

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?

No guidance on when to use this tool versus alternatives like file_facts or file_preflight. Without exclusion criteria or context, agents may misuse it when a more specific tool is appropriate.

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 and idempotentHint=true. The description adds value by confirming it returns a 'read-only packet' and listing the contents, but does not disclose error behavior or edge cases. No contradiction with 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?

The description is concise, using three sentences to convey purpose and usage. It is front-loaded with the core function and avoids redundancy, though could be slightly more compact.

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 (10 parameters, composite output) and the presence of annotations and an output schema, the description adequately covers the operational context. It omits error handling and prerequisites but is sufficient for typical use.

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 has 10 parameters with 0% description coverage. The description only mentions the return items and not the parameters like freshnessPolicy, cacheStalenessMs, or limits. The description does not compensate for the missing schema descriptions, providing minimal parameter guidance.

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 identifies the tool as a pre-edit composer for one file, listing the specific data it returns (findings, freshness, runs, etc.) and distinguishing it from sibling tools like file_findings, verification_state, etc., by stating it replaces multiple separate calls.

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 tool explicitly states when to use it ('Use before editing a file when an agent needs the operational gate') and mentions what it replaces, but does not provide explicit when-not-to-use scenarios or prerequisites, slightly reducing clarity.

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 indicate destructiveHint=true and readOnlyHint=false. The description adds value by noting that it returns a snapshot id for undo, providing behavioral 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?

Two concise sentences front-load the purpose and outcome. No redundant 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?

Given the presence of an output schema and annotations, the description covers the key behavior and return value (snapshot id). It could mention error handling or directory creation, but overall adequate for a write 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 baseline is 3. The description repeats 'project-relative path' already in schema and does not add semantic meaning beyond what the schema 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 explicitly states 'Create or overwrite a file at a project-relative path', using a specific verb and resource. It distinguishes itself from sibling tools like 'create_file' and 'file_edit' by specifying overwrite behavior.

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 does not provide explicit guidance on when to use this tool over alternatives. No comparison to sibling tools or conditions for exclusion is given.

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 mark it as a mutation, and the description adds valuable behavioral details: append-only, deduplication at query time, and emission of a RuntimeUsefulnessEvent. No contradictions with 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?

The description is front-loaded with the purpose and reasonably concise. It uses technical but accurate language. Slightly verbose in the middle, but overall efficient.

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 complex tool with 14 parameters and no output schema, the description covers the main operation, duplicate behavior, and event emission. However, it omits explanation of several optional parameters and does not fully describe the return value, leaving some gaps.

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?

With 0% schema description coverage, the description adds meaning for key parameters (category, fingerprint, subjectKind) but leaves many optional parameters (e.g., acknowledgedBy, sourceToolName) unexplained. The core required ones are clarified.

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 (append), resource (finding_acks ledger), and purpose (filter out matches for subsequent callers). It differentiates from sibling tools like finding_ack_batch and finding_acks_report.

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 clear context on when to use which fingerprint based on source (ast_find_pattern vs lint_files) and mentions the default category for lint findings. It does not explicitly compare with the batch variant, but the guidance is sufficient for correct invocation.

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 provides behavioral details beyond annotations: it is a mutation (consistent with readOnlyHint=false), it emits one telemetry event per successful row, and it shares batch-level defaults. No contradiction with 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?

Two sentences covering definition, use case, and side effects. No redundant information; each sentence adds unique value. Front-loaded with the core purpose.

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 gives essential context: batch operation, defaults, use case, and telemetry. With an output schema present, return values are covered externally. However, it does not mention error handling behavior (continueOnError parameter) or row structure details, leaving some gaps for a tool with 12 parameters and nested rows.

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 lists the default parameters that can be shared across rows (category, subjectKind, status, reason, etc.), adding meaning beyond the schema which has 0% description coverage. However, it does not explain all parameters (e.g., projectId, projectRef, preview, continueOnError, row fields like label, filePath, fingerprint). The baseline is 3 due to low coverage, and description partially compensates but not fully.

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?

Description clearly states it's a mutation batch for finding acknowledgements, appending multiple rows with batch-level defaults. It identifies the specific resource (finding_acks) and verb (batch append), and distinguishes itself from the singular 'finding_ack' sibling by emphasizing batch operation and defaults.

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: 'Use when a scan returns many reviewed false positives or accepted tradeoffs.' It implies this is the batch alternative to the singular 'finding_ack', but does not explicitly mention when not to use or list alternative tools.

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