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

With no annotations, the description discloses important behavioral traits: it is a pure regex scan with no index, implying potential performance characteristics, and it prioritizes results based on current_files. This adds useful context beyond a simple 'scan' statement, though it does not explicitly mention that it is read-only or describe exact output 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 extremely concise, consisting of three short sentences that each add value: purpose, method, and usage tip. It is front-loaded with the core function and contains no redundant or unnecessary 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's simplicity, the description is mostly complete: it conveys purpose, method, and usage guidance, while the schema fully documents parameters. The main gap is that there is no output schema and the description does not describe the return format or ordering, but the tool name and purpose strongly imply a list of TODOs, so it remains adequate.

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 all three parameters described in the schema. The tool description adds little beyond reinforcing current_files ('Pass current_files to boost'), which is already captured in the schema. The description does not introduce new parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool's action ('Scan TODO/FIXME/XXX/HACK') and its purpose ('prioritize by current work'). It is specific and distinguishes this tool from siblings like code_quality or code_review, which focus on broader analysis rather than TODO scanning.

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 by explaining the tool's lightweight nature ('Pure regex, no index') and suggests boosting via current_files. However, it does not explicitly state when NOT to use it or name alternative tools, so it lacks explicit exclusions. Still, the usage context is clear for a TODO scanner.

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

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

With no annotations provided, the description must carry the behavioral disclosure burden. It explains that the tool works at a line level and returns callers/callees, but does not detail return format, pagination, or any potential side effects. For a simple query tool, this is adequate but not rich.

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 extremely concise, using two short sentences with no fluff. It front-loads the core purpose and immediately provides usage context. Every word contributes to clarity.

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 moderate complexity (7 parameters, no output schema), the description is largely sufficient. It explains the core use case and points to a sibling for symbol-level queries. However, it omits any mention of return structure or behavior details like depth limits, which are in the schema but not described. Still, it is reasonably complete for a query tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds little to parameter understanding beyond what is already in the schema. The line/symbol relationship is already captured in the schema's anyOf and descriptions. No additional semantic meaning is provided.

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

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

The description clearly states the tool's function: 'Callers/callees at a line'. It specifies the resource (line) and the operation (retrieving callers and callees). It also distinguishes itself from the sibling tool impact_analysis by explicitly noting the line-based vs symbol-based use case.

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

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

The description provides explicit guidance: 'use when you know line, not symbol name' and direct the user to impact_analysis for symbol-level queries. This clearly indicates when to use this tool versus an alternative.

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

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

With no annotations, the description carries the full burden. It explicitly states the tool is read-only, which is a key behavioral trait not evident from the schema. It also discloses the output format (5-dim JSON with named dimensions). No annotations are present to contradict these claims.

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 extremely concise: one sentence plus a short conditional clause. It front-loads the most important information (read-only, 5-dim JSON scores) and uses minimal words to convey scope and alternatives. Every phrase earns its place.

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

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

For a tool with two required params and no output schema, the description covers the essential purpose, output structure, and a pointer to related functionality. However, it does not explain the meaning or scale of the scores, which could be unclear in some contexts. Still, it is reasonably complete for a focused 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% for both parameters, so the schema already documents them. The description adds no additional meaning about the parameters, such as format constraints or relationships to the output dimensions, so it meets the baseline but does not exceed it.

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 indicates the tool returns a 5-dimensional JSON quality score with specific dimensions, and distinguishes itself from code_review by pointing to that tool for findings. However, it lacks an explicit verb like 'computes' or 'returns,' making it slightly less direct than ideal.

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 explicitly mentions an alternative tool ('Findings? code_review'), which provides clear guidance on when to use this tool vs. code_review. It does not discuss other sibling tools, but the specific conditional alternative is valuable and sufficient for common 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?

No annotations are provided, so the description carries full burden. It discloses deterministic regex, zero LLM, and the shape-level scope, which are valuable behavioral traits. Yet it omits side effects (e.g., whether it reads or writes files), permission requirements, or return format, which are important for a tool with no output schema.

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

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

Two concise sentences front-load the essential qualifier ('Shape-level code check, deterministic regex, zero LLM') and include avoidable filler. Every phrase adds value, such as 'clears shallow noise before deep review.'

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 tool has 5 parameters and no output schema, so the description must carry more weight. It explains purpose and scope, and the 'max_issues' parameter implies a list of issues is returned, but the return structure and interpretation guidance are not described. This is 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?

Schema coverage is 100%, so the baseline is 3. The description adds context about the types of checks performed (naming, comments, etc.) that map to expected outputs, but it does not clarify parameter precedence or add meaning beyond the schema's own 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 it performs a 'shape-level code check' covering naming, comment coverage, long functions, duplicated blocks, and diff review. It distinguishes itself from correctness-focused tools by noting it is 'not a correctness verdict,' but does not explicitly contrast with siblings like 'code_quality' or 'style_sniffer.'

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

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

The description gives clear usage context: use it to 'clear shallow noise before deep review,' implying it is a preliminary check. It also excludes correctness judgments. However, no alternative tool names are mentioned, so guidance on when not to use specific siblings is absent.

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?

Without annotations, the description carries the full burden. It clearly discloses that matching is 'DETERMINISTIC token+intent matching, NOT semantic/embedding search' and warns that long sentences degrade to loose file-level hits. This is useful behavioral context. It does not explicitly state read-only behavior, but that is implied by a search tool.

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

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

The description is two sentences long, front-loaded with the core purpose, and every clause adds value—from distinguishing symbol_search to explaining the deterministic algorithm and its failure mode. This is economy of prose.

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 no output schema, the description covers the essential context: when to use the tool, how it behaves (deterministic token matching), its limitations (degraded NL queries), and a preferred alternative. For a search tool with these specifics, this is complete and well-rounded.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for the query parameter ('NL intent search' and the warning about long sentences), but does not significantly enhance the schema definitions for limit or workspace_dir. It provides some extra meaning for query but is not essential to understand the required 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 explicitly states 'NL intent search when symbol name unknown', providing a specific verb ('search') and resource ('symbols'). It also distinguishes from the sibling tool 'symbol_search' by noting the known-name alternative, making the tool's purpose 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?

It gives explicit when-to-use guidance: use when symbol name is unknown, and points to symbol_search as the alternative for known names. It also advises preferring precise symbol/file names over long natural-language queries, which is actionable usage direction.

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 indicates a read-only operation via 'Detect', and the schema adds a prerequisite to reindex if the workspace is new. However, it does not explicitly state that no modifications are made, nor does it describe output format or permission requirements. With no annotations provided, these behavioral details are missing, leaving some gaps.

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, consisting of a single clear sentence stating the purpose and a brief note about pairing with exception_guard. It is front-loaded with the core action and contains no filler or 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?

This simple detection tool has a complete parameter schema but no output schema and no annotations. The description does not explain what the tool returns or what the agent should expect as a result, which is a significant gap given the lack of output schema. The crucial prerequisite about reindexing is only present in the schema, not the main description, and overall the description could provide more context for a complete understanding.

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 fully documents both parameters (workspace_dir and file), including a required flag and a clear description for file with the option to omit for full scan. The tool description itself does not add parameter-specific meaning, but with 100% schema description coverage, the 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 detects env vars, DB tables, and services missing from .env.example or docker-compose, using the specific verb 'Detect'. It also notes a pairing with exception_guard, which adds context and helps distinguish it from sibling tools like code_quality or security_review.

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 an implied usage context for detecting config drift and hints at a complementary relationship with exception_guard. However, it lacks explicit guidance on when to use this tool versus alternatives, when not to use it, or any exclusions. The guidance is minimal and somewhat vague.

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

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

With no annotations, the description carries the transparency burden. It adds meaningful behavior details: 'Deterministic, zero LLM', script-mode auto-runtime selection, and 14 error types with 4-language stack traces. However, it does not mention potential side effects of running arbitrary commands (e.g., file modifications, network access), which would be important for a command execution tool.

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

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

The description is three concise sentences with no fluff. The first sentence fronts the primary purpose and outputs, while the second adds a key behavioral detail (script mode runtime selection) and the third states determinism. Every sentence contributes 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 no output schema, the description compensates by detailing the analysis output (14 error types, 4-language stack traces, suggested actions) and key behavior (deterministic, zero LLM). It lacks a bit on success-handling or side effects, but the core context is covered, especially with rich parameter descriptions in the 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 description coverage is 100%, and the schema already documents each parameter thoroughly (e.g., script auto-picks runtime, pass exactly one of command/script/test). The description does not add significant parameter-level meaning beyond what the schema provides, so the 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 tool runs a command/script/test and analyzes failures, with specific features like 14 error types and 4-language stack traces. This verb+resource combination distinguishes it from sibling tools (e.g., test_bridge, tsc_check) by emphasizing execution plus automated failure analysis.

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?

There is no explicit guidance on when to use this tool versus alternatives such as test_bridge or find_tests. The description implies general debugging use but does not provide exclusions or compare against sibling tools, leaving the agent to infer applicability.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only vaguely indicates a read/check operation ('Imports vs manifests', 'undeclared deps'). It does not mention side effects, permissions, reindex requirements, or output format. The schema hints at reindexing but the description itself is insufficient.

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 extremely concise, using a compact phrase that conveys core purpose and supported languages. It is front-loaded and has no wasted words, though it may be too terse for full clarity, it is appropriately sized for the limited content.

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 no output schema, the description must explain return values and expectations, but it says nothing about what results look like or how 'install hints' are presented. It also does not mention prerequisites beyond implicit reindexing. The description is too incomplete for an agent to confidently invoke and interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context about the tool's purpose but does not provide specific parameter-level details beyond what the schema already states; it merely implies the file parameter is source code and workspace_dir is the root.

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 function: comparing imports against manifests to list undeclared dependencies and provide install hints, while listing supported languages (Py/JS/Go/Rust). It distinguishes itself by mentioning the relationship with guard_patterns, although it does not fully separate it from other siblings.

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

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

No explicit guidance on when to use this tool versus alternatives. The phrase 'Pairs with guard_patterns' hints at a complementary relationship, but there is no concrete when-to-use or when-not-to-use instruction, leaving the agent to infer usage from the terse description.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It implies a read-only operation via 'import' and describes output for project mode, but it does not explicitly state read-only status, side effects, or prerequisites like reindexing. This leaves some ambiguity.

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, information-dense sentences that front-load the primary purpose and immediately provide alternative tool pointers. No wasted words; every phrase 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?

The description covers the main use cases, project output structure, and alternative tools. It omits file-mode output specifics, but given the schema's completeness, this is sufficient. The complexity level is moderate and well-addressed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates schema information (file, depth, scope) without adding new semantics. It clarifies the two modes, but that is already present in the schema.

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

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

The description clearly states the tool's function: generating an import dependency graph. It specifically distinguishes between file-level (transitive N levels) and project-level (nodes/edges/cycles) use cases, making it distinct from sibling tools like fix_imports and impact_analysis.

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

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

Explicit usage guidance is provided: 'Circular deps? fix_imports. Changing a dep? impact_analysis first.' This tells the user when not to use this tool and points to specific alternatives, which is excellent contextual guidance.

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

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

With no annotations provided, the description carries the full burden. It mentions the output format (JSON) and the content (AST changes + caller/test sync), but does not disclose whether the tool is read-only, has side effects, or requires any special setup beyond being post-edit_transaction.

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 extremely concise and information-dense. Every part serves a purpose: the timing, the content, the format, and the pointer to an alternative. 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?

For a tool with no output schema and no annotations, the description provides the essential context (when to use, what it returns, format, alternative), but it remains cryptic. It doesn't explain what 'caller/test sync' entails or the structure of the JSON, leaving ambiguity for an agent without domain knowledge.

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 provides 100% coverage with descriptions for both parameters. The tool description adds no additional parameter-specific meaning, so the 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 indicates the tool provides AST changes and caller/test sync information in JSON format, specifically after an edit_transaction. It distinguishes itself from sibling tools by referencing test_bridge for stale tests, but it lacks an explicit verb like 'get' or 'list'.

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 explicitly states the timing ('Post-edit_transaction') and provides an alternative tool for a specific condition ('Stale tests? test_bridge.'). This gives clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the burden. It discloses atomicity of multiple edits, dry-run preview capability, and the read-first requirement. However, it does not explicitly warn about file modification side effects or partial-failure behavior, though these are evident from the schema and the word 'edit'.

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

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

Three short, dense sentences that front-load the must-use directive and immediately capture purpose, usage, and alternatives. Every sentence earns its place with zero filler.

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

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

For a single-file edit tool with a detailed schema, the description covers the essential behavioral context: atomicity, dry-run preview, and the alternative path for other scenarios. It doesn't mention return values or partial-failure handling, but the schema fills those gaps, and the tool is relatively straightforward.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds minimal parameter-specific insight beyond the schema, mainly tying dry_run to diff preview and emphasizing atomic multi-edit behavior, but no new semantic details.

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 says 'MUST USE for all file edits' and 'PREFERRED single-file edit path', naming the resource (files) and the action (edit). It also distinguishes itself from edit_transaction, which is for rollback/multi-file scenarios, making it clear among siblings.

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

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

It provides explicit when-to-use guidance ('MUST USE for all file edits'), a prerequisite ('Read first, then edit'), and names an alternative for other cases ('Rollback/multi-file? edit_transaction').

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?

No annotations are provided, so the description must carry the behavioral burden. It discloses the two-step workflow and the fact that external edits are detected, but does not explain what happens on detection, where snapshots are stored, or whether the guard has side effects. The integration hint with edit_transaction is vague.

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 sentences convey the core workflow and purpose without wasted words. The structure is front-loaded with the tool's purpose and steps, making it easy to scan.

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

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

Despite having no output schema or annotations, the description explains the core workflow but omits return values, failure behavior, and session handling implications. Given the tool's relatively low complexity, this is adequate but leaves gaps that an agent would need to infer or discover.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'record_read (snapshot) after reading, check before editing' essentially restates the exact semantics already in the action parameter's enum descriptions, adding no new information for parameter use.

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

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

Clearly defines a two-step guard mechanism with specific actions (record_read and check) and its purpose of detecting external edits before modifying a file. Distinguishes itself from siblings by explicitly pairing with edit_transaction.

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

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

Provides explicit timing guidance: record_read after reading, check before editing. Mentions pairing with edit_transaction, giving contextual fit. Does not mention alternatives or exclusions, but the usage pattern is clear.

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

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

With no annotations, the description discloses the transactional workflow (begin→edit→commit) and mentions rollback/preview/undo, indicating state management. It also warns about JSON escaping inconsistencies causing client-side parsing failures. While not detailing every side effect, it provides meaningful behavioral context beyond the schema.

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

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

Three sentences, front-loaded with purpose, followed by usage guidance and a technical caution. 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?

For a complex tool with 9 parameters and 7 actions, the description leverages the schema's parameter descriptions and adds the core workflow and usage context. While an example would be helpful, the combination of schema and description is sufficient for a capable agent.

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

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

Schema covers 100% of parameters, but the description adds workflow context linking actions (begin→edit→commit) and practical guidance on consistent JSON escaping for string parameters containing quotes or backslashes. This goes beyond 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?

Clearly states it is the default multi-file edit path with transactional operations (begin, edit, commit, rollback/undo). Explicitly distinguishes from edit_batch for single-file edits, providing a specific verb+resource and sibling differentiation.

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 when unsure about changes' and directs single-file edits to edit_batch. This gives clear when-to-use and alternative guidance.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals module/project scoping and suggests a fix capability via 'Fix → verify test_bridge'. However, it is ambiguous whether the tool actually modifies files or only reports, and it does not disclose side effects, permissions, or failure modes.

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 extremely concise, fitting purpose, scope, workflow, and a sibling reference into one sentence. It is front-loaded with the main verb and resource. The arrow notation is compact but slightly ambiguous, though it earns its place by conveying multiple pieces of information 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 two-parameter tool with no output schema or annotations, the description provides a reasonable overview. It explains the check scope, hints at fix verification, and pairs a related tool. However, it leaves significant gaps: what the output looks like, whether fixes are direct file modifications, and how to interpret results. The mention of test_bridge is vague without explaining what it does.

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 descriptions for both workspace_dir and file, so the baseline is 3. The description adds context about module scoping that relates to how the file parameter is interpreted, but it does not directly add semantics to the parameters themselves 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 clearly states the tool's primary function: 'Check raise/throw uses project exceptions vs builtins'. This is a specific verb+resource that distinguishes it from generic checking tools. However, it does not explicitly contrast with sibling tools like guard_patterns, only pairing with config_drift, so it's clear but not fully differentiated.

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

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

The description implies usage contexts through 'module-scoped (falls back to project scope)' and the workflow 'Fix → verify test_bridge'. It also pairs with config_drift, giving hints about when to use. However, it lacks explicit 'use this when' or 'instead of' guidance, so usage is inferred rather than clearly prescribed.

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

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

With no annotations, the description carries the burden. It adds the behavioral detail that reports are 'collected locally,' which informs the agent about data handling. However, it does not disclose whether the operation is persistent, what response to expect, or any side effects beyond collection.

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 compact sentence with no unnecessary words. It front-loads the action and includes a key detail (local collection) with minimal verbosity. The minor typo 'malong' does not warrant a reduction.

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 feedback tool with no output schema, the description provides the core purpose and a local-collection detail, but it omits return behavior and leaves 'malong' unexplained. Given the simplicity, it should at least mention what happens after reporting. This is a clear gap.

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 provides full descriptions for all four parameters (tool, issue, note, error_code), so baseline is 3. The description does not add any parameter-specific 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 the tool's purpose: reporting issues/errors/ideas. The verb 'Report' and resource 'tool issues/errors/ideas' are specific, and no sibling tools serve a similar function. However, the term 'malong' is ambiguous and not defined, slightly reducing clarity.

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 when encountering tool issues/errors/ideas, but does not explicitly state when-to-use vs alternatives. Since no sibling tools are similar, it's acceptable, but there is no guidance on prerequisites or what qualifies as feedback.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It reveals the auto-fresh re-indexing behavior and notes when explicit reindex is needed, which is useful. However, it doesn't explicitly state whether the operation is read-only, what side effects occur during auto-fresh, or what return format to expect, leaving gaps in transparency.

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

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

The description is only two sentences, with the purpose stated first and the essential behavioral note (auto-fresh) in the second. Every word earns its place; there is no fluff or redundancy.

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

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

This tool has no output schema and no annotations, so the description should cover key context. It explains what it does and the auto-fresh behavior, and points to test_bridge. However, it lacks any mention of return format (e.g., paths) and what 'import reverse lookup' entails, which could be important for an agent to gauge if the tool meets its needs. Given the simple scope, this is adequate but not complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's phrase 'naming + import reverse lookup' adds semantic nuance to how the 'file' parameter is used, but it doesn't elaborate on 'symbol' or 'workspace_dir' beyond schema. It adds marginal value without compensating for any missing parameter details.

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 'Find' with a clear resource ('test files for a source file') and explains the mechanism ('naming + import reverse lookup'). It also distinguishes itself from test_bridge, a sibling tool, by explicitly pointing to test_bridge for running tests.

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 explicitly says 'Run them? test_bridge', which tells the agent to use test_bridge for execution, providing a clear when-not-to-use and alternative. It also gives context about when explicit reindex is needed (brand-new workspaces/files) and that auto-fresh handles modified files, informing usage decisions.

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?

No annotations are provided, so the description carries the full burden. It mentions 'auto_fix applies' but does not explicitly disclose that files may be modified when auto_fix is true, nor does it describe output format, side effects, or prerequisites like reindexing.

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 very concise and front-loaded, but the second sentence 'auto_fix applies' is incomplete and could be integrated more clearly. Overall, it wastes no words but could be structured more effectively.

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 lack of annotations and output schema, the description is too sparse. The tool can modify files (via auto_fix), but the description does not explain return values, side effects, or when to use it, making it incomplete for safe 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 100%, so the baseline is 3. The description adds no extra meaning about parameters; 'auto_fix applies' simply echoes the auto_fix parameter without elaborating on candidate handling or defaults.

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's purpose: detecting unused imports, undefined symbols, and circular dependencies, with an auto-fix option. It uses specific verbs and resources, but does not explicitly state the scope (e.g., per file vs project) or differentiate from similar sibling tools like dep_graph or code_quality.

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?

There is no guidance on when to use this tool versus alternatives such as dep_graph, sweep_dead_code, or code_quality. The description only states what it does, leaving the agent to infer appropriate 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?

With no annotations provided, the description must fully disclose behavioral traits. It mentions the prerequisite --expose-gc but does not indicate side effects (e.g., blocking, cost, or that it forces a full GC). This leaves the agent uncertain about what actually happens.

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 short sentences with no filler. It is front-loaded with the action and immediately follows with a usage condition, making it 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?

For a zero-parameter tool with no output schema, the description covers the core purpose and usage context. However, it omits behavioral details like what triggers the GC or any return value, which would make it fully complete for an agent.

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 tool has zero parameters, and the schema is complete (100% coverage). The description adds no parameter-specific information, so the baseline of 4 applies as no parameters need explanation.

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 ('Trigger manual GC') and includes a necessary prerequisite ('needs --expose-gc'). It is specific and distinct from sibling tools, which are unrelated development utilities.

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 a clear usage condition ('Use when memory is high') but does not mention when not to use it or alternative tools. This is good context but lacks exclusions or alternatives for a top score.

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

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

With no annotations, the description carries full burden. It discloses key behaviors: changes are made on an isolated branch, committed and fast-forward merged, verification via verify_cmd can abort and rollback on failure. This is substantial disclosure for a mutation tool, though it doesn't detail rollback mechanics or return values.

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 with a colon and list, conveying purpose, benefits, and safety features. Every phrase adds value, 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?

The description covers the core workflow (multi-file changes, commit, merge, verify, rollback) but doesn't specify the return value or the exact lifecycle of the worktree/branch. Given no output schema or annotations, this is a minor gap but overall sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions verify_cmd and rollback, but the schema already documents each parameter thoroughly. The description adds no new 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 the tool applies multi-file changes on an isolated git branch with auto commit and ff-merge, including verification and rollback. It distinguishes itself from generic edit tools by specifying the worktree isolation and safety mechanisms.

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 transactional multi-file changes that should not pollute the working tree, with verification via verify_cmd. It doesn't explicitly name alternatives or exclusions, but the mention of isolated branch and zero pollution provides clear context for when to prefer this tool.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does add context about the specific AST rules, custom config, and its role as a pre-commit gate. However, it does not state whether the tool is read-only, what it returns (e.g., a pass/fail report, violations list, exit codes), or any side effects. This is a notable gap for a tool without annotations, but the provided context is not misleading.

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

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

The description is three concise fragments that are front-loaded with 'AST rules' to immediately convey the core purpose. Each sentence adds distinct value: what rules are enforced, how to customize, and how it integrates as a pre-commit gate. There is no redundancy or filler.

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

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

The tool is relatively simple with only three parameters and no output schema, but the description does not explain what the tool returns or the effects of a violation (e.g., blocking a commit). The integration note about dependency_gatekeeper is vague. The schema covers parameters, but the description should at least hint at the tool's output or behavior when a pattern is found; it falls short of that.

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 provides detailed descriptions for all three parameters (file, ruleset, workspace_dir), giving 100% coverage. The description adds no parameter-specific information beyond what the schema already contains. Since the schema carries the load, a 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 identifies the tool as enforcing AST rules for specific forbidden patterns (bare-except, debugger, eval), and mentions custom rules via .ai-patterns.json. The verb 'guard' is implied by the name and reinforced by 'Pre-commit gate', but it does not explicitly contrast with sibling tools like code_quality or style_sniffer, so it loses a point for lack of sibling differentiation.

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 as a pre-commit gate, especially 'with dependency_gatekeeper', and suggests customization via a config file. However, it does not provide explicit when-to-use vs alternatives, exclusions, or prerequisites (e.g., needing to reindex first, as hinted in workspace_dir description). This is implied usage, not explicit guidance.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It mentions 'self-healing' and actions like restart/cleanup, implying mutating behavior, but does not disclose potential destructive consequences, permission requirements, or what 'restart' entails. The description does not go beyond what a reader would infer from the action names.

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 just two short sentences, front-loaded with the core purpose and followed by the action list. Every phrase contributes meaning, with no filler or redundancy.

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

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

The tool has four optional parameters and no output schema or annotations, so the description needs to provide sufficient context. It gives a solid high-level overview but omits details like what 'restart' actually does, what 'tools' refers to, and whether the tool returns a report. The schema covers parameter specifics, but the description is not fully complete for a self-healing 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?

The input schema provides 100% coverage of all four parameters with detailed descriptions, so the baseline is 3. The description's mention of action names adds no additional meaning beyond the schema's already-documented definitions of check, restart, and cleanup.

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 performs a 'system check + self-healing' covering DB integrity, tools, memory, and semaphore, and lists actions check/restart/cleanup. This distinguishes it from many sibling tools focused on code analysis, though it does not explicitly contrast with overlapping tools like 'gc' or 'reindex'.

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 is provided on when to use this tool versus alternatives such as 'gc' or 'config_drift'. The action list implies some usage context, but there are no explicit conditions, exclusions, or alternative tool mentions.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It adds useful context about auto-reindexing and the risk metric, but it doesn't state whether the operation is read-only, potential side effects, or error conditions. The provided details are valuable but not comprehensive.

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

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

The description is compact and front-loaded, using shorthand to convey multiple key points in two sentences. Every phrase earns its place, though the telegraphic style ('BEFORE modifying/renaming:', 'Line-level? call_chain. Simple edit? read_symbol+write_symbol.') sacrifices a bit of readability.

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 9 parameters and no output schema, the description provides essential context: primary use case, alternatives, auto-fresh indexing behavior, and core outputs (callers, callees, risk). It doesn't describe the return format in detail, but the schema covers parameters, and the description covers the decisions an agent needs to know when to choose this tool.

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

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

The input schema already documents all 9 parameters with 100% coverage, so the baseline is 3. The description adds minimal parameter-specific semantics beyond mentioning blast radius and risk, but it does not explain any parameter nuances that aren't in the schema. It does not need to, given the schema's thoroughness.

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: perform impact analysis before modifying or renaming by showing callers (blast radius), callees, and risk based on caller-count. It also distinguishes itself from siblings by explicitly directing line-level analysis to call_chain and simple edits to read_symbol+write_symbol, leaving no ambiguity about what this tool provides.

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

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

Provides explicit when-to-use guidance ('BEFORE modifying/renaming') and contrasts with alternatives ('Line-level? call_chain. Simple edit? read_symbol+write_symbol.'). It also clarifies the auto-fresh indexing behavior, indicating when an explicit reindex is needed. This is exemplary usage guidance.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It explains that the tool aggregates three outputs, but does not explicitly state it is read-only, nor does it mention prerequisites (e.g., reindexing) or output format caveats. Some useful context is present, but gaps remain.

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 immediately conveys the tool's function and its relationship to sibling tools. It is concise 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 schema covers all parameters and the description explains the high-level purpose, the tool is adequately described for selection and invocation. The lack of an output schema is partly mitigated by naming the three components, though a more detailed description of the combined return structure 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?

All six parameters are documented in the schema with descriptions, and the description does not add meaning beyond what the schema already provides. The mention of 'outline + references + call chain' maps to the boolean parameters, but the schema already covers this, so the baseline score of 3 applies.

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

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

The description clearly states the tool combines outline, references, and call chain in a single call, and explicitly mentions it replaces read_outline/references/call_chain. This makes the purpose immediately clear and distinguishes it from sibling tools.

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

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

The phrase 'replaces read_outline/references/call_chain' explicitly tells the agent when to use this tool instead of those alternatives. This is clear, actionable guidance on tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the tool is read-only, what output or side effects occur, or any required permissions or preconditions beyond the schema's reindex notice. This is a significant gap for a tool that detects issues.

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 short, front-loaded sentences with no redundant words. 'Detect mock/patch mismatches after signature changes' immediately states the core purpose, and 'Pairs rename_symbol' adds workflow context with minimal verbosity.

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 tool has no output schema, no annotations, and the description does not explain what the tool returns, whether it modifies anything, or the exact scope of 'mock/patch mismatches.' The 'Pairs rename_symbol' hint is useful, but the overall context is incomplete for an agent to safely and effectively 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?

The input schema has 100% description coverage, and the parameters are clearly documented (e.g., 'REQUIRED: project root (abs). reindex first if new.'). The tool description adds no additional parameter-level meaning, so the baseline of 3 is appropriate since the schema already provides sufficient semantics.

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

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

The description clearly states the tool's function: 'Detect mock/patch mismatches after signature changes.' This uses a specific verb ('detect') and resource ('mock/patch mismatches'), and the phrase 'after signature changes' connects it to a specific workflow, distinguishing it from siblings like rename_symbol.

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 usage context: 'after signature changes' and 'Pairs rename_symbol' explicitly links it to a workflow step. However, it does not explicitly state when not to use it or mention alternative tools, though the sibling context makes the pairing clear.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It mentions 'Index required,' which is a dependency, but does not indicate whether the tool is read-only, what it returns, or any side effects. This is insufficient for an agent to understand the tool's 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 very concise, consisting of one sentence and a fragment. It is front-loaded with the core purpose and does not waste words. However, it is slightly terse and could be clearer, but overall appropriately sized for a simple 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 lacks essential context such as return values, operational effects, and usage examples. There is no output schema, so the description should explain what the tool returns (e.g., violations list). It also does not clarify read-only behavior, making it incomplete for an AI agent.

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 covers all 4 parameters with 100% coverage, so the schema already provides parameter descriptions. The description adds the 'Index required' note, which is a prerequisite but not directly about parameter semantics. Thus, it meets the baseline but does not significantly enhance parameter understanding.

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

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

The description states the tool checks new symbol names against project naming style (snake/camel/Pascal) and verb consistency, which is a specific function. It differentiates from siblings like style_sniffer and code_quality by focusing on symbol naming consistency, though it could be more explicit about comparing to existing conventions.

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 is provided about when to use this tool versus alternatives like style_sniffer or code_quality. The only usage hint is 'Index required,' which is a prerequisite but not a usage context. There is no mention of scenario fit or exclusions.

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

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

With no annotations, the description carries the full burden. 'Dry-run apply' discloses that the tool is non-destructive, which is a key behavioral trait. However, it omits expected return values, error handling, and any side effects, leaving ambiguity about what happens after parsing.

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 sentences, no filler. Each clause delivers essential information: the action, the resource, the dry-run behavior, and the intended context. Ideal economy.

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 tool is simple and the schema covers parameters, but with no output schema and no annotations, the description does not explain what the tool returns on success or failure. It is sufficient to invoke but not to interpret results, leaving a completeness gap.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description merely repeats that the 'text' parameter contains SEARCH/REPLACE content, adding no extra semantic value 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 the tool parses SEARCH/REPLACE patch text and dry-run applies it. 'For external patch blocks' distinguishes this from sibling tools that likely perform actual edits, providing a clear scope and resource.

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 phrase 'For external patch blocks' implies usage context, but no explicit alternatives or when-not-to-use guidance is given. The condition is stated but not elaborated with exclusions or related 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?

With no annotations, the description carries the transparency burden. It discloses the key behavioral limitation ('no full read') and clarifies depth semantics, adding value beyond the schema. Yet it does not mention whether the tool is purely read-only, whether it requires indexing, or what the return format is, leaving some behavioral aspects undisclosed.

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 extremely concise, packing critical info into two short sentences and a question. It is front-loaded with the core purpose and every clause adds value without redundancy.

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

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

For a read tool with 6 parameters, the description gives a clear outline of purpose and a sibling pointer. It lacks explicit mention of call depth alternatives and return details, but the schema covers parameters and the tool name implies read-only behavior. Overall, it is adequate but could slightly expand on when to use call_chain.

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 each parameter is already documented. The description adds a useful clarification that depth means hierarchy nesting, not call depth, but this largely reinforces the schema's existing 'Hierarchy depth' description. Baseline 3 is appropriate.

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

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

Description clearly states the tool reads file structure (functions/classes/signatures) rather than full content, and explicitly distinguishes from read_symbol. The phrase 'no full read' clarifies scope, matching the tool name.

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

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

Provides clear guidance for the known-symbol case ('Known symbol? read_symbol'), and 'depth=hierarchy nesting, NOT call depth' implicitly directs call-depth analysis elsewhere. However, it does not explicitly name call_chain or other alternatives for full reads, so some usage context is missing.

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?

No annotations are provided, so the description carries the full burden. It discloses auto-fresh re-indexing behavior, resolution modes (symbol_id or name+file), and base_version relevance for writes. However, it does not describe error handling or the exact return payload beyond 'body + version', preventing a 5.

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

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

Three dense sentences, each earning its place: prerequisite, core function, and alternatives/auto-fresh. No fluff or redundancy, well front-loaded.

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 10-parameter tool with no output schema, the description covers the key decisions: what it reads, how to resolve symbols, when to use read_outline, and reindex behavior. The schema details the rest, so the description is complete enough for an agent to select and invoke 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 description coverage is 100%, so baseline is 3. The description adds value by explaining resolution via symbol_id or name+file, and mentions base_version for writes, which is not in the schema. This raises it to a 4.

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

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

Description clearly states it reads symbol body and version, resolves by symbol_id or name+file, and explicitly distinguishes from read_outline for full files. The verb 'read' is explicit and the resource is a symbol, with sibling differentiation.

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 'MUST READ BEFORE WRITE', provides an alternative ('Full file? read_outline'), and clarifies when reindexing is needed (brand-new workspaces/files). This gives clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the transparency burden. It discloses the AUTO-FRESH re-indexing behavior and the need for explicit reindex only for new workspaces/files. It also mentions usage counts. No contradictions.

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

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

The description is extremely concise: two sentences plus a brief auto-fresh note. Purpose is front-loaded, all sentences carry meaning, and there is zero fluff.

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

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

For a simple query tool with full schema coverage, this is quite complete. It explains the core behavior, usage counts, path requirement, and indexing behavior. However, it does not describe the return format or possible failure modes, which would be needed for a 5.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the full member path requirement for the symbol parameter and clarifying workspace_dir reindex behavior, which goes beyond 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 the tool's function: 'Cross-file usages of a symbol, incl. usage counts.' This is a specific verb+resource pairing. However, it does not explicitly differentiate from sibling tools like trace_symbol or call_chain, though 'cross-file usages' is distinct enough.

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

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

Provides clear usage context: 'Use full member path (obj.method).' and 'Prefer over grep.' It gives a practical comparison and a requirement, but does not explicitly mention when not to use or name specific sibling alternatives, which would make it a 5.

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

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

With no annotations, the description carries the full burden. It discloses the two-step confirmation, blocking/force options, and its prerequisite nature, but does not mention side effects (e.g., overwriting index), whether it's a write operation, timeout behavior, or what happens if run without confirmation. Some transparency is provided, but gaps remain.

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 short and front-loads the critical 'MUST run FIRST' directive. However, it is fragmented into three rough segments with some redundancy ('MUST run FIRST' and 'before ALL other malong tools' overlap). Still, it earns its place without excess.

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 workflow is complex (8 optional params, no output schema), and the description covers the crucial confirm process and prerequisite status. However, it doesn't describe return values (e.g., needs_review response with token), explain why indexing is required, or state what happens if skipped. It's adequate but not complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'blocking/force options' and the confirm flow, but these are already captured in the schema. It adds no new meaning about parameters (e.g., force semantics, maxFiles upper bound).

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 indexes a workspace and positions it as the mandatory first step for all malong tools. The verb 'index' and resource 'workspace' are explicit, and the phrase 'before ALL other malong tools' distinguishes its role from siblings.

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

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

Explicitly instructs to run FIRST, provides the two-step confirm procedure for over-threshold workspaces, and mentions blocking/force options. This gives clear when-to-use guidance and preconditions, though it doesn't name alternatives (none needed for a prerequisite).

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 key behaviors: 'Word-boundary, string/comment-aware' explains the matching semantics, reducing risk of unintended replacements. 'dry_run previews' explains the behavior of the dry_run parameter. It also notes the transaction-based nature. These details are essential since no annotations 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?

The description is exceptionally concise: three sentences, each packed with information. It front-loads the core purpose and uses no filler words, making it easy for an agent to parse quickly.

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 potentially destructive cross-file rename tool, the description provides context about word-boundary awareness and dry_run, and directs to impact_analysis for preview. It doesn't explain return values or error handling, but the existence of sibling tools like edit_transaction and sandbox_validate likely covers those aspects. Given its complexity, the description is mostly 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?

The input schema already contains complete parameter descriptions (100% coverage), so the tool description adds limited additional meaning. The description's mention of 'dry_run previews' reinforces the dry_run parameter's purpose but doesn't clarify formats or relationships 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 clearly states the tool's function: 'Execute a cross-file symbol rename (edit_transaction-based).' It specifies the verb (execute), resource (symbol rename), and scope (cross-file), and differentiates it from related tools like read_symbol and write_symbol by focusing on renaming and mentioning the edit_transaction basis.

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

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

The description provides explicit guidance: 'To see what a rename would affect FIRST, use impact_analysis.' This directs the agent to use a preview tool before executing a rename, which is an alternative context. However, it doesn't explicitly mention when not to use this tool or compare with other sibling tools like edit_batch or edit_transaction.

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

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

With no annotations, the description must carry the transparency burden. It adds useful context about token efficiency and scale, but does not disclose whether the tool is read-only, requires indexing, or what the output structure looks like. This is partial coverage beyond the structured fields.

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

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

The description is extremely concise, consisting of two short fragments with no redundant words. It front-loads the purpose and ends with a practical usage hint.

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 the core mapping concept and a key usage tip, but lacks explicit information about return format, side effects, or prerequisites like reindexing. Given no output schema and no annotations, this is adequate but leaves notable 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 100%, so baseline is 3. The description adds the combined usage tip 'focused+relevantEntities for token efficiency', which is not present in the schema and explains how to use two parameters together for a specific purpose.

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 'Project code map: files ↔ symbols', indicating a mapping operation between files and symbols. It distinguishes itself from sibling tools by positioning as a repository-scale overview ('For 100+ file codebases'), though it doesn't explicitly contrast with symbol_search or dep_graph.

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 phrase 'For 100+ file codebases' implies intended use on large repositories, which provides some context. However, there is no explicit mention of alternatives or when not to use, and the 'focused+relevantEntities' tip is about parameter usage rather than tool selection.

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

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

With no annotations provided, the description carries the burden. 'Dry-run' implies no side effects, which is a key behavioral trait. However, it does not disclose what happens on failure (e.g., does it throw an error, return a report?), nor whether it accesses the filesystem beyond reading. The description is minimal but not misleading.

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 extremely concise—two short sentences. The main purpose is front-loaded ('Pre-validate edits'), followed by essential guidance. Every word earns its place, with no fluff 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?

The tool is relatively simple, but there is no output schema, so the description should explain return behavior or error handling. It does not describe what the dry-run returns (e.g., success/failure, syntax errors). It also doesn't mention side effects or workspace directory requirements, although the schema covers parameters. For a pre-validation step, agents may need to know how to interpret results, so this is a notable gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that new_content is 'full new text', reinforcing that it should be the entire file content, which is a useful nuance beyond the schema's 'or the edited section'. It also names the two key parameters directly, tying them to the validation purpose.

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: 'Pre-validate edits' with a 'dry-run syntax check'. It identifies the specific resource (file edits) and action (validate), and distinguishes itself from the sibling 'edit_transaction' by explicitly directing the user to use that afterward. The verb 'pre-validate' is 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?

The description gives clear context: use this tool before edit_transaction, as indicated by 'Then edit_transaction.' It implies this is a pre-flight check for edits. However, it does not explicitly state when not to use it or mention alternatives like edit_collision_guard, so it's slightly lacking in exclusion guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses that results are severity-graded, that the tool uses zero LLM, and mentions suppression via malong-ignore or .ai-patterns.json. It doesn't detail return format or side effects, but this is reasonable context for a scan tool.

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

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

The description is two sentences, starts with the main action and scope, and packs additional info (suppression, out-of-scope, zero LLM) into a structured list. There is no wasted verbiage, making it highly scannable.

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

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

Given no output schema and moderate complexity (5 params), the description covers the essential context: what patterns are scanned, exclusions, suppression, and the zero-LLM behavior. It doesn't describe return structure beyond 'severity-graded,' but it is sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description mentions 'severity-graded' and suppression but does not add parameter-specific meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Scan') and a concrete resource ('security patterns') followed by a detailed list of pattern categories (injection, XSS, secrets, CORS*, insecure compare). This clearly distinguishes it from sibling tools like code_review or code_quality, which would target broader or different concerns.

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 lists what is covered (injection, XSS, secrets, CORS*, insecure compare) and what is out of scope (SSRF/XXE/deserialization/auth), which gives clear when-to-use and when-not-to-use guidance. It stops short of naming alternative tools directly, but the exclusions imply the boundary well.

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

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

With no annotations, the description carries the burden. It discloses a key behavior: 'never writes files', which is useful. However, it does not mention required preconditions (e.g., reindexing), permission needs, or error behavior. The in-memory return is a significant safety trait but additional behavioral context would strengthen the description.

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 a clear verb, and no redundant words. Every phrase earns its place, efficiently conveying both purpose and a key behavioral guarantee.

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 tool is simple (2 params, no output schema), and the description covers purpose and a critical safety trait. It lacks details on return structure or prerequisites, but these are minor gaps for a spec generator with good schema coverage. Slightly more behavioral context (e.g., side-effect-free in more detail) would make 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 description coverage is 100%, so the baseline of 3 applies. The description adds minimal parameter context beyond 'from source symbols', which hints at the file's role but does not explain the parameters in depth. The schema descriptions already clarify both parameters adequately.

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 verb 'generate' is specific and the resource is clearly defined as 'module/API spec from source symbols'. It distinguishes from siblings like write_symbols (writes symbols) and read_symbol (reads symbols). The phrase 'never writes files' further clarifies its non-mutating role.

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 safe, read-only operation by stating 'returns in-memory spec, never writes files'. This gives clear context but does not explicitly name alternative tools or state when not to use it. It could benefit from an explicit reference to a sibling like write_symbols, but the context is strong enough.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions that output is optional and returns text, but it does not disclose that setting an output directory writes a file (potentially overwriting unless force=true). This significant side effect is only revealed in the schema, not the description.

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 front-loading the core action. Every phrase contributes to understanding the tool's function and output, with no filler or unnecessary details.

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

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

The description covers the high-level purpose and return behavior but omits details about file-writing side effects, the force parameter's overwrite behavior, and when to use this tool. Given no annotations or output schema, it is somewhat incomplete but sufficient for a basic understanding.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema, only noting that output is optional. It does not provide additional semantic context for required workspace_dir or the force/scope 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 sniffs project code style from samples and generates PROJECT_RULES.md content, with an optional output directory. The verb 'sniff' and resource are specific, and it distinguishes the tool's purpose from generic code-quality tools, though it does not explicitly differentiate from siblings.

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

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

The description implies usage when style rules need to be extracted from existing code, but it does not explicitly say when to use this tool versus alternatives or when not to use it. No exclusions or comparable tools are 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?

Even with no annotations, the description discloses the critical behavioral trait: 'Text-reference fallback counts CLI-string refs as alive (miss-over-delete bias)'. This is an honest limitation that helps the agent calibrate expectations. Also clarifies it is detection-only, pointing removal elsewhere, and states an exclusion.

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, front-loaded with the purpose, and every phrase earns its place: categories, bias, removal path, and scope exclusion. 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?

For a tool with no output schema and a moderate parameter set, the description provides sufficient context: what it detects, its detection bias, how to act on results, and what is out of scope. It could mention the return format or signal structure, but that is a minor gap given the clarity of the description and 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 description coverage is 100%, so the schema already documents all three parameters. The description adds no parameter-specific detail beyond what the schema provides, but it does mention 'unused_guard signal' as an output concept, not a parameter explanation. Baseline 3 is appropriate because the description doesn't need to compensate.

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: 'Detect dead code' and enumerates specific categories (unused imports/functions, orphan files). This is a specific verb+resource combination that distinguishes it from sibling tools like dep_graph or references.

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

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

The description gives clear context for use: detection of dead code with a bias toward false negatives. It explicitly notes out-of-scope cases (dynamic/reflection wiring) and points to edit_transaction for removal. However, it does not explicitly name alternative detection tools or state when to prefer this over dep_graph or 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the auto-fresh behavior (files modified after last index are re-indexed automatically on read) and clarifies when explicit reindex is needed. This adds meaningful context beyond a simple search call, though it does not detail potential side effects or permissions.

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

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

The description is compact: purpose, sibling routing, and freshness behavior in two sentences. Every clause adds value, and the information is front-loaded. 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?

The description fully prepares an agent to choose and invoke the tool: it explains the search semantics, distinguishes from related tools, covers the auto-fresh behavior, and clarifies reindex needs. With no output schema, return format is not specified, but the description is complete for a search tool.

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

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

Input schema coverage is 100%, with each parameter already having a description. The AUTO-FRESH note reinforces the workspace_dir requirement ('reindex first if new') but does not add new meaning beyond the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description opens with 'Find symbol definitions by name (substring)', clearly stating the verb and resource. It then distinguishes from siblings by routing usages/references to 'references' and pre-edit impact to 'impact_analysis', making the specific purpose 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?

The description gives explicit when-to-use guidance: 'Usages? references. Before edit? impact_analysis.' It also clarifies when reindex is needed via the AUTO-FRESH note, telling the agent that explicit reindex is only necessary for brand-new workspaces/files. This is direct and actionable.

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

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

With no annotations, the description carries the full burden. It discloses that the tool parses output and enriches failures, adding behavioral insight beyond simple test execution. It does not mention side effects, environment requirements, or return format, leaving some transparency gaps.

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 extremely concise, with key information (purpose and actions) front-loaded. Every word adds value, and the pointer to find_tests is a useful, compact addition.

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 7 parameters, no output schema, and no annotations, the description is minimal. It does not describe the return value, the precise difference between 'discover' and find_tests, or how actions affect behavior. This leaves significant context gaps for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself adds no new parameter semantics beyond what the schema already provides; it only echoes the action enum.

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: 'Run tests, parse output, enrich failures with context.' It also enumerates the three actions (run/suggest/discover), and explicitly points to find_tests for test discovery, distinguishing it from that sibling.

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 usage context by listing actions and redirecting test discovery to find_tests. However, it does not explain when to prefer this over other test-related siblings like debug_runner or verify_pipeline.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the operation is read-only, any side effects, performance implications, or return format. The only hints come from parameter descriptions in the schema, not from the main description.

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 extremely concise (two short sentences) and front-loaded with the core purpose. It avoids fluff and efficiently points to alternatives, achieving maximum clarity per word.

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

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

The description covers the core purpose and alternatives, and the schema documents all parameters. However, without an output schema or annotations, the description doesn't convey what results to expect or how to interpret them. It's adequate for a simple trace tool but lacks some context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal semantic value; it hints at the tool's purpose (tracing constants) which clarifies the symbol parameter, but it doesn't explain parameter interactions or specifics 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 the tool's function: tracing constant values and hardcoded copies (magic numbers). It also distinguishes itself from siblings by explicitly pointing to alternatives (impact_analysis for function impact, rename_symbol for renaming), making its scope 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?

The description explicitly tells the agent when to use this tool (for value tracing) versus when to use alternatives: 'Function impact? impact_analysis. Rename? rename_symbol.' This provides clear exclusion guidance and alternative routing.

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

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

With no annotations, the description carries the burden. It discloses the command, output shape, timeout, and directory behavior, but it does not explicitly state that this is a read-only operation or mention potential side effects (e.g., creation of incremental cache files).

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 with no waste, but 'dir = subdir' is a bit terse. It is front-loaded with the main action and output format.

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 tool with no output schema and no annotations, the description provides enough context: it states the command, output shape, timeout, and directory scoping. Missing an explicit safety note, but this is a type-check tool and non-mutating behavior is implied.

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

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

Schema coverage is 100% with parameter descriptions, so baseline is 3. The description adds value by clarifying that `dir` refers to a subdirectory and confirming the timeout default (`60s`), which enriches 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?

Clearly states the tool runs TypeScript type-checking via `tsc --noEmit` and summarizes the output as `{status,errorCount}`. The verb and resource are specific, and it is distinct from sibling tools like code_quality or code_review.

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 type-checking a subdirectory, but it does not explicitly state when to use it over alternatives like code_quality or sandbox_validate. No exclusions or prerequisites are 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?

No annotations provided, so the description carries full burden. It discloses the critical timeout behavior, including the hard 120s limit and per-stage defaults, and warns about timeouts for large test suites. It does not specify return format or potential side effects of running scripts, but the most important behavior is covered.

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

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

Three sentences, with the purpose in the first sentence and crucial warnings/alternatives in the following two. Each sentence earns its place, no filler.

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

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

For a 4-param tool with no output schema and no annotations, the description provides clear purpose, timeout warnings, and alternatives. It could mention what the return value looks like (e.g., logs, exit codes), but the absence is not critical given the tool's nature. The 'reindex first if new' tip is present in the schema, so it's covered.

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

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

Schema covers all parameters with descriptions, so baseline is 3. The description adds value by elaborating on the timeout parameter's default (30s per stage) and suggesting stage filtering for time-sensitive runs, complementing the schema's field-level details.

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

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

The description states a specific action: 'Run lint/test/typecheck from package.json.' It clearly identifies the resource and scope, and distinguishes from test_bridge by naming it as an alternative for full test runs. However, it does not explicitly differentiate from tsc_check, which could overlap with the 'typecheck' stage.

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 alternatives: 'Large test suites will time out — prefer stages=lint or test_bridge(action=run) for full test runs.' Also provides context about the 120s hard timeout and per-stage defaults, giving clear situational guidance.

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

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

With no annotations, the description carries the transparency burden. It discloses guarded write semantics, version/lock/undo, base_version requirement, and a client-side JSON escaping pitfall. It doesn't detail permissions or side effects, but adds meaningful behavioral context beyond the schema.

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

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

Three focused sentences, each earning its place: purpose/vs-alternative, read-prerequisite, and a critical parameter formatting caveat. No fluff, well front-loaded.

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 11-parameter tool with nested objects and no output schema, the description provides the key mental model, prerequisite, and a critical gotcha. It doesn't explain all edit modes or safety knobs, but those are documented in the schema. Lacks explicit success/failure behavior, though.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the JSON escaping requirement for string parameters and reinforcing that base_version comes from read_symbol, which is not fully obvious from the schema alone.

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 this as a guarded write path for a single symbol with version/lock/undo, and explicitly distinguishes it from edit_batch for symbol-level refactors. The resource (one symbol) and operation type are 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?

It gives a direct comparison to edit_batch, stating this is for symbol-level refactors with index-aware version/lock/undo. It also instructs to read_symbol first for base_version, providing a clear prerequisite. It doesn't enumerate all alternatives but offers key exclusions.

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

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

With no annotations provided, the description carries the transparency burden. It discloses key behaviors: atomicity ('All-or-nothing across files'), concurrency safety ('deadlock-safe'), and a client-side parsing pitfall (JSON escaping). These go beyond what the schema conveys, though it doesn't describe error handling beyond the atomicity trait.

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

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

The description is three sentences, each earning its place: purpose+behavior, usage guidance+alternative, and a specific parameter caveat. It is front-loaded with the most important info and contains no fluff.

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

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

For a complex tool with 5 parameters and nested objects, the description covers the essential contextual aspects: atomicity, deadlock-safety, usage trigger, and a real-world pitfall. It does not explain return values, but no output schema exists, so that's less critical. Given the rich schema, the description is sufficiently 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 baseline is 3. The description adds a valuable parameter-related nuance: the JSON escaping warning for string params, which is not present in the schema's per-parameter descriptions. This extra guidance justifies a 4.

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

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

The description clearly states it is a 'Guarded write path (batch)' with 'All-or-nothing across files', specifying both the verb (write) and resource (batch of files). It distinguishes itself from the sibling tool write_symbol by explicitly recommending 'Multi-file refactor? Use instead of N×write_symbol'.

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 explicitly gives a when-to-use scenario ('Multi-file refactor?') and an alternative ('Use instead of N×write_symbol'). It also adds a prerequisite ('New symbols: reindex first'). However, it does not explicitly state when NOT to use it or mention other alternatives like edit_batch, so it falls short of a 5.

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