plumb

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

With no annotations, the description carries the full burden and excels: it discloses that write access is gated by a user setting, lists safety-critical exclusions, and explains atomicity, provenance tagging, and one-step revertibility. This is rich behavioral context beyond what the schema provides.

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 dense but every sentence carries important information about permissions, atomicity, and usage. It is slightly long, but the detail is warranted for a security-sensitive config 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?

For a 3-parameter tool with a nested object and no output schema, it covers operation semantics, write gating, allowed keys, and side effects well. The only minor gap is explicit error behavior when set is called while writes are disabled, but this is reasonably implied by 'Writing is OFF unless...'.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by naming allowlisted key categories and giving an example (tasks.go.test). This goes beyond the schema's generic 'map of dotted config key to value' and helps the agent understand what can be set.

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 reads and conditionally writes a small allowlist of plumb config keys, listing specific categories like task commands, log level, and theme. It distinguishes itself by focusing on agent configuration management rather than general file operations.

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

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

It provides a concrete use case ('set up a repo's build/test commands') and explains the describe/set workflow, indicating when to use describe first. It implicitly excludes general file edits but does not explicitly name alternative tools, which would push it to 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 full burden and does well: it discloses the fallback to topology, marks it as 'approximate', explains the snapping behavior when a raw position lands off an identifier, and warns about off-by-one errors. No contradictions with annotations. Minor gap: no mention of return shape or pagination, but the key behaviors are transparent.

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

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

The description is concise yet information-dense. It front-loads the core purpose, then layers usage guidance, input preferences, and fallback behavior in a logical order. Every sentence adds value, and 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?

Given the tool's complexity (two input modes, direction enum, fallback path), the description covers the essential aspects: what it does, preferred vs. fallback input, fallback to topology, and a use case. It does not describe the output structure (e.g., tree format), but in the absence of an output schema, this is a minor omission for a hierarchy 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?

Even though schema coverage is 100%, the description adds meaningful semantics: it explains why symbol_name is preferred (avoids off-by-one and 'no identifier found' errors), describes the ReceiverType.MethodName form, and clarifies that line/character are unnecessary when symbol_name is provided. This goes beyond the schema's basic 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 'Show the call hierarchy for a symbol: who calls it (incoming) and what it calls (outgoing)', using a specific verb and resource with scope. It distinguishes from siblings like find_references and type_hierarchy by explicitly naming the call direction and fallback behavior.

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

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

It provides clear context: 'Useful for understanding control flow and assessing the impact of changes.' It also explains when the topology fallback applies (e.g., zls for Zig) and prescribes preferred input over fallback. However, it does not explicitly contrast with alternative tools like find_references, so it stops short of full when/when-not 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 and exceeds it: it discloses once-only delivery across three paths, that re-calling will not redeliver, that listing consumes nothing on the recipient's behalf, the blocking/timeout capping behavior, the [collab] mailbox = true requirement, and that plumb does not push. This is rich behavioral context far beyond what annotations would have supplied.

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 long but front-loaded with the core purpose, and nearly every sentence carries unique behavioral or routing information. The final 'Parameters:' line mildly duplicates the schema's wait_seconds description, a small redundancy, but the density of genuinely new information justifies the length.

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 no output schema and no annotations, the description covers an exceptional amount: delivery paths, once-semantics, threading via conversation_id, own-unread reporting with age, config requirement, and wait capping. The one gap is the exact return shape/fields, which the description only touches via conversation_id and age; with no output schema, that duty falls on the description.

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 schema already fully defines wait_seconds including the cap. The description adds marginal strategic meaning beyond the schema — that a positive wait 'hands your turn to a peer instead of polling' and that the cap is 'kept below the client's own call timeout' — which an agent cannot infer from the bare parameter description.

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

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

The description opens with a specific verb-plus-resource statement — 'Read messages other agents have sent you' — then scopes it precisely: 'Receive half of plumb's mailbox; leave_note is the send half.' It also discloses a second purpose (reporting your own unread mail), so an agent knows the full scope without opening any schema.

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

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

It names the sibling alternative (leave_note as the send half) and points to the plumb-chat skill for full etiquette rules. It gives explicit when-to conditions for the wait behavior ('hand your turn to a peer instead of polling') and explains the immediate-return path ('Omit wait_seconds (or 0) to return immediately'). Nothing about selection is left to inference.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that permissions are preserved, parent directories are created, overwrite is refused by default, cross-device copies work, and the LSP server is notified (FileCreated) for immediate diagnostics. This is comprehensive and goes well beyond the basic schema.

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

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

The description is concise (three sentences) and well-structured: it starts with the primary purpose, then covers behavioral details, and ends with a pointer to an alternative. Every sentence contributes unique value; 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?

For a file copy tool with four parameters and no output schema, the description provides complete context: purpose, key effects (permissions, parent directories, LSP notification), safety (overwrite refusal), technical capability (cross-device), and differentiation from sibling. The absence of an output schema is acceptable, as the description explains the outcome sufficiently.

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 parameters (to, from, dirty_ok, overwrite) are fully documented in the schema. The description adds slight context by reiterating overwrite behavior and parent directory creation, but these are already present in the parameter descriptions. Thus it meets the baseline without significantly enriching 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 states the exact action ('Copy a file to a new path') and explicitly distinguishes from the sibling 'rename_file' by instructing to use it for move/rename. It also names the resource and key behaviors clearly, leaving no ambiguity about the tool's purpose.

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

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

The description explicitly tells the user when to use an alternative tool ('To move or rename a file, use rename_file instead'), and provides usage context such as automatic parent directory creation, overwrite behavior with the overwrite=true flag, and cross-device support. This is clear guidance on when and how to use the 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 full responsibility for behavioral disclosure. It goes into exceptional detail about what is returned, including conditions like 'when available' for workspace-pin provenance and 'on a mismatch' for protocol revision. It also reveals performance-related data (tool-call count, slowest calls) and config-store state, giving a thorough picture of the tool's observational nature.

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

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

The description is front-loaded with the primary purpose, but it consists of one extremely long, comma-heavy sentence that enumerates many details. While every detail is informative, the lack of sentence breaks makes it harder to parse. A shorter, bulleted or multi-sentence structure would improve readability without losing 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?

Given the tool's complexity (no output schema, no annotations), the description compensates fully. It covers all return categories, conditional behaviors, and usage context, making it self-sufficient for an AI agent to understand what to expect. The lack of output schema is mitigated by the exhaustive list of returned metadata fields.

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 empty (100% schema coverage by default). The description need not explain parameter meanings. Baseline for 0 params is 4, and there is no need to compensate further.

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 'Returns metadata about the current MCP session and daemon process' with a specific verb and resource. It enumerates the exact aspects covered (session name, ID, daemon version, etc.), making it easily distinguishable from sibling tools like workspace_symbols or read_file. The closing 'Use this to identify which session you are operating in or to verify the daemon state' reinforces the purpose.

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

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

The description provides explicit guidance on when to use the tool: 'Use this to identify which session you are operating in or to verify the daemon state.' It does not explicitly mention alternatives or when not to use it, but given the uniqueness of the tool among its siblings, the context is sufficient.

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 behavioral disclosure. It details the non-recursive delete restriction, the refusal of non-empty directories, validation before any removal, the order of directory deletion, LSP notification, per-path locking against concurrent writes, and the response report format. This is exhaustive for a complex mutation 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 long, but every sentence delivers new information—no filler. It front-loads the core action and follows with restrictions, deletion strategy, side effects, and response format. The structure is logical, though slightly dense; a compact breakdown of the tree-deletion workflow would improve scanability.

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 annotations and no output schema, the description covers all necessary operational aspects: path types, batching limits, rejection rules, tree deletion method, concurrency behavior, side effects, and response contents. An agent has sufficient information to call this tool correctly without further inference.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds meaningful semantics beyond the schema: it clarifies that paths batches round-trips, enforces a max of 100, explains validation and ordering, and explicitly contrasts file_path with paths ('Use paths instead to delete several in one call'). This extra context moves it above baseline.

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

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

The description opens with 'Delete files and empty directories,' giving a specific verb, resource, and scope. It clearly distinguishes from siblings like write_file, edit_file, rename_file, and copy_file by focusing purely on deletion and adding the nuance that non-empty directories are rejected.

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 clarifies when to use this tool and how to handle tree deletion: 'To remove a whole tree, list its files with find_files and pass them plus their directories in one paths batch with allow_dir: true.' It also notes the batching alternative to file_path and warns against recursive deletion, giving the agent precise routing 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 carries full burden for behavioral disclosure. It does specify the exact directory being modified and adds a safety condition, but it omits critical details such as permanence/irreversibility of deletion and error behavior. This leaves some ambiguity for a destructive operation.

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

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

The description is two sentences long and front-loads the action and target. The second sentence adds a necessary usage boundary. There is no redundancy or filler; every word serves a purpose.

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

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

The description adequately explains what the tool does, where it operates, and when it should be used, which is sufficient for a simple delete operation with two well-documented parameters. It lacks explicit mention of irreversible consequences or return values, but those are not required given the absence of an output schema and the straightforward nature of the operation.

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 provides 100% coverage for both parameters ('name' and 'workspace') with clear descriptions. The tool description does not add parameter-specific semantics, which is acceptable given the high schema coverage, but it also doesn't supplement any missing nuance about parameter usage.

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 ('Delete a memory by name'), the specific resource (memory in .plumb/memories/ directory), and the workspace scope. This distinguishes it from sibling tools like delete_file and other memory operations.

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 second sentence provides explicit usage guidance: 'Use only when explicitly asked, or when the memory has clearly become obsolete' with a concrete example. This establishes both when-to-use and when-not-to-use, effectively preventing accidental misuse.

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 explicitly states that results are pushed asynchronously by the language server, may be empty if no diagnostics have been sent yet, and that a report labelled INCOMPLETE during server warm-up means a clean result does not prove the code compiles. This is exemplary transparency about potential pitfalls.

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

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

The description is concise yet thorough, using four sentences to cover purpose, parameter usage, batching efficiency, and critical behavioral caveats. Each sentence earns its place, and the structure front-loads the core purpose before diving into 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?

Given the tool's complexity—asynchronous LSP results, potential empty diagnostics, and the INCOMPLETE label—the description covers all necessary context. It explains parameter variations, the push-based nature, and the implication of results during server warm-up, providing a complete picture for an agent without needing an output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the deprecated uri parameter, the behavior of omitting or passing [] for uris, and that a multi-URI call replaces multiple single-file calls. Minor issue: the description says 'file:// URIs' while the schema allows absolute and relative paths, but this is a simplification that the schema clarifies.

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

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

The description clearly states the tool returns LSP errors, warnings, and hints for one file, several files, or the whole workspace, using a specific verb and resource. It distinguishes itself from sibling tools like search_in_files or find_references by focusing on diagnostics, making its purpose unmistakable.

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

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

The description provides clear context on when to use the tool: pass specific URIs to check those files, omit or pass [] to query all files, and batch multiple URIs in one call to replace multiple single-file calls. It does not explicitly name alternatives or exclusions, but the guidance is sufficient to determine appropriate use.

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 and does so thoroughly. It discloses atomic crash-durable writes, per-path locking, dirty-file refusal and dirty_ok override, expected_mtime/expected_sha concurrency checks, exact-match rejection, anchor newline behavior, apply_partial failure continuation, diagnostics labeling, and fail_on_new_errors rollback 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 dense and front-loaded, with no filler sentences. It is somewhat long, and some details overlap with schema field documentation, but the length is justified by the tool's complexity and the absence of annotations.

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

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

For a 13-parameter mutation tool with no output schema and no annotations, the description is remarkably complete. It covers modes, concurrency, atomicity, dirty-file handling, failure behavior, diagnostics, and how to select among alternative tools. The only minor omission is a formal return-shape description, but response behavior is alluded to in enough places.

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, but the description adds substantial semantic value beyond the schema: mutual exclusivity of the two request shapes, when to prefer range mode over str_replace mode, exact-once uniqueness requirements, how anchors interact with spans, and the safety implications of reconcile, apply_partial, and fail_on_new_errors.

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

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

States a specific action and resource: 'Apply one or more edits to an existing file'. It also explicitly routes the agent away from a native edit tool and toward specialized symbol tools for named declarations, which distinguishes it from relevant 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?

Provides explicit when-to-use guidance: prefer this over a native edit tool, prefer range-based edits for large multi-line replacements, and prefer replace_symbol_body / insert_before_symbol / insert_after_symbol / safe_delete_symbol for whole named declarations. Also references a skill for deeper mode choice.

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 behavioral burden, and it discloses substantial traits: hover content format (Markdown), positional lookup fallback behavior, off-by-one error avoidance via symbol resolution, and snapping to the enclosing symbol when a position lands off an identifier. It does not state what happens when a symbol is not found, but it covers the major behavioral gotchas.

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?

Roughly four sentences, front-loaded with the primary purpose, followed by the preferred invocation path, the usage condition, and the sibling alternative. Every sentence earns its place, though it is slightly wordier than strictly necessary with some inline parentheticals.

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 moderate-complexity tool with no output schema and no annotations, the description covers the return format, both invocation modes, fallback behavior, and the alternative tool. The main missing piece is failure behavior (e.g., return value or error when the symbol cannot be resolved), which prevents 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 description coverage is 100%, so the baseline is 3, but the description adds genuine value beyond the schema: it establishes that symbol_name is the preferred invocation form and explains why (plumb resolves the identifier, avoiding off-by-one errors), and it describes how line/character behaves when it misses an identifier (snapped to the enclosing symbol). This preference ordering does not exist 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 states a specific verb and resource: 'Returns DOCUMENTATION and type information (LSP hover content: function signature, doc comment, often in Markdown)'. It clearly distinguishes this from get_definition by explicitly naming the sibling, so an agent can tell them apart immediately.

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 explicit when-to-use statement ('Use when you need to understand what a symbol is without navigating to its source') and names the exact alternative ('For the file location of where the symbol is defined, use get_definition instead'). It also instructs which invocation form to prefer (name over position), leaving nothing to inference.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly indicates a read-only diff operation, works outside git, and explains the effect of two parameters. It does not explicitly state that files are not modified, but that is implicit in the 'diff' operation. Slightly more detail about potential edge cases could improve it, but the core behavior is transparent.

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

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

The description is compact and front-loaded, stating the purpose in the first sentence. It contains only 41 words and every sentence carries functional information, such as the git alternative and parameter hints.

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, with all four parameters documented in the schema. The description clearly states the return format (unified diff), provides usage guidelines, and references relevant parameters. Given no output schema, the description adequately covers what is needed for an agent to invoke this tool effectively.

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 covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by explaining how context_lines and ignore_whitespace affect the output, reinforcing the schema's semantics without merely duplicating 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 states the tool returns a unified diff between two files, with a specific verb and resource. It also explicitly contrasts with the git tool's diff subcommand, effectively distinguishing it from a sibling tool.

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

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

The description provides explicit guidance on when to use this tool instead of the git tool (for non-tracked files) and mentions how to control context and whitespace handling. This directly addresses usage alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers: it describes the output format (signature lines, nesting, byte-precise line ranges), the fallback mechanism between language server and tree-sitter, the source annotation behavior, and the effect of include_docs=false. This is a rich, transparent account of what the tool actually does.

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 appropriately sized and front-loaded with the core purpose. Each sentence adds distinct information: what it returns, why to use it, the fallback source behavior, and the include_docs flag. No waste; every sentence earns its place.

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

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

For a tool with no output schema and no annotations, the description is remarkably complete: it covers the return shape, use case, fallback behavior, and parameter semantics. The token-cheap rationale and the concrete example of a 2000-line file make it self-sufficient for an agent to decide when and how to invoke it.

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

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

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds value beyond the schema by clarifying that include_docs controls whether leading doc-comment lines are prepended and that the default is true, which gives the agent meaningful behavioral context for parameter choice.

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

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

The description uses a specific verb ('Return') and resource ('a token-cheap skeleton of a file'), then enumerates exactly what is included: functions, types, methods, classes, constants with signature lines and collapsed bodies. It clearly distinguishes itself from siblings like read_file or read_symbol by emphasizing the high-level structural overview rather than content.

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 to use this tool 'to understand a large file's shape in one call without reading it,' which gives a clear when-to-use context. It contrasts with reading the file itself by mentioning a 2000-line file becomes a few hundred tokens, though it does not explicitly name alternatives or state when not to use it.

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 behavioral burden. It discloses read-only semantics, that it does not read content, how fields like last_writer are determined, and that missing files are reported rather than causing an error. It also flags the strict mode limitation, adding valuable 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?

The description is a single paragraph but tightly packed. It front-loads the core purpose, then details outputs, then gives usage guidance and exclusions. Every sentence adds necessary information; there is no verbiage 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?

There is no output schema, so the description must explain return semantics, which it does thoroughly by defining each field. It also covers edge cases (missing files), usage context (avoiding blind re-reads, pairing with read_file), and a key limitation (strict mode). Given the tool's complexity, the description is complete.

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

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

Schema description coverage is 100% for the single 'paths' parameter, so the baseline is 3. The description does not add new parameter-level detail beyond what the schema already states (absolute paths, file:// URIs, or workspace-relative paths), but it does reinforce that the tool reports per path without introducing ambiguity.

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 clear, specific verb and resource: "Lightweight, read-only 'did this file change under me?' check." It enumerates exact outputs (git_dirty, changed_since_plumb_wrote, last_writer, mtime, size) and explicitly notes it does not read content, distinguishing it from read_file and similar siblings.

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

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

The description gives explicit when-to-use guidance: "Use before re-editing a file you read or wrote earlier to confirm your view is still current, instead of a blind re-read." It also names an alternative (read_file) and states when not to rely on it: "it does not satisfy strict mode's read-before-edit requirement."

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 reveals workspace scoping, .gitignore exclusion, stats recording, cross-host consistency, and optional pattern behavior. It also clarifies output formats (bare path list or details with markers), making the tool's behavior transparent despite being read-only.

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 block of four sentences, front-loaded with the core purpose, then contrasts with shell tools, then explains key behaviors. It is dense but every sentence contributes value; it lacks fluff, though it is longer than necessary compared to highly concise examples.

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-only search tool with 10 parameters and no output schema, the description is thorough: it covers purpose, scope, limitations, parameter behavior, and output formats. It is self-contained and leaves little ambiguity for an agent deciding when to invoke 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 covers all 10 parameters at 100% with detailed descriptions, so the schema carries the heavy lifting. The tool description adds a narrative summary (e.g., 'pattern is optional — omit it to list everything' and 'max_depth=1 lists one level, like ls'), but these points already exist in the schema, providing no additional meaning beyond what is already structured.

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 'Workspace-scoped file/directory finder and directory lister,' identifying the specific action and resource. It additionally distinguishes itself from shell find/fd/ls and sibling tools like search_in_files by clarifying its scope and function.

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 contrasts with shell find/fd/ls, highlighting the workspace confinement and .gitignore exclusions, which guides when to use this tool. It mentions consistent pattern semantics across hosts, but it doesn't explicitly reference sibling tools like search_in_files for content-based searches, leaving those alternatives unmentioned.

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 return values (file path, line number, source line), the snapping behavior when a position lands off an identifier, and the advantage of using a symbol name. This goes beyond a simple statement of purpose.

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, return values, and parameter guidance. It is front-loaded with the main function 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?

Given the tool's simplicity and the absence of an output schema, the description covers the essentials: what it does, what it returns, and how to provide input correctly. It could mention limitations or sorting order, but these are not critical.

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 value by explaining the preferred parameter combination (uri + symbol_name) and why it is preferred (avoiding off-by-one errors), as well as the fallback behavior. This clarifies the relationship between parameters 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: 'Find all references to a symbol across the entire workspace.' This is a specific verb+resource with a clear scope, and the mention of 'across the entire workspace' distinguishes it from narrower symbol tools.

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

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

The description gives clear guidance on how to call the tool (prefer a name over a raw position) but does not explicitly mention when to use this tool versus alternatives like get_definition or call_hierarchy. The use case is implied rather than explicitly contrasted with siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers richly. It discloses the dry_run safety default, the show_write_diff config and its per-file unified diff output with the 20-file cap and '+N more' summary, the binary-file detection via null-byte sniff of first 8 KB, the max_file_bytes skip, .gitignore honoring, glob pruning behavior, and parallel processing with sorted output. This is comprehensive operational transparency well 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?

The description is front-loaded with the core purpose in the first sentence, followed by a natural progression: safety default, output format, skipping rules, and routing guidance. The prose is efficient; every sentence adds operational value. The only slight deduction is that a few details (glob pruning, parallel processing) could arguably be tightened, but the content is all high-value and nothing is wasted.

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 no annotations and no output schema, the description is unusually complete. It covers the safety default (dry_run), the accepted path formats (absolute, file:// URI, or workspace-relative), the output behavior (unified diff with file cap), skip rules (binary, size, .gitignore), glob semantics, formatting behavior after writes (with failure as warnings), and tool selection. An agent has everything needed to call it correctly and predict its effects.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantic value beyond the schema: it explains the smart-case default behavior for case_sensitive, clarifies that replacement supports $1/$2 backreferences in regex mode, and clarifies the glob directory-prefix pruning optimization. However, it does not explicitly walk through every parameter (e.g., dirty_ok is covered in schema but not in the description prose). Given the high coverage, the added semantics push slightly above baseline but not to the top.

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 precise verb+resource: 'find text across files with optional replacement' and immediately names the directory-tree scope. It explicitly contrasts itself with rename_symbol (scope/type-aware identifier refactor vs plain-text edits), which distinguishes it from the closest sibling. The title and verb are not merely restated; the description adds operational meaning.

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 is unusually explicit about usage: it states the default dry_run=true preview-first workflow, lists concrete applicability examples (doc strings, license headers, hostnames, version strings, non-code files), and names the alternative tool rename_symbol for identifier refactors. It effectively tells an agent when NOT to use this tool and which sibling to prefer.

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 transparency burden. It goes beyond a simple definition lookup by disclosing fallback behavior ('snapped to the enclosing symbol') and the rationale for preferring symbol_name (avoids off-by-one and 'no identifier found' errors). It doesn't mention side effects or error cases, but for a read-only navigation tool, the disclosed behavior is sufficient.

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, preference/behavior, and when-to-use/alternative. It is front-loaded with the most important information and contains 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?

For a simple definition-lookup tool, the description covers purpose, input preferences, fallback behavior, and alternative tool. The absence of an output schema is mitigated by explicitly stating what is returned (file path + line number). All parameters are described in the schema, and the description adds the necessary contextual glue. Nothing critical is missing.

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

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

Schema coverage is 100% and each parameter is described, so the baseline is 3. The description adds meaningful semantic guidance by explaining why symbol_name is preferred over line/character and explicitly stating that line and character are not needed when symbol_name is provided. This goes beyond the schema's individual parameter descriptions.

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

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

The description opens with a specific verb+resource: 'Returns the SOURCE LOCATION (file path + line number) of where a symbol is defined,' making the core purpose unmistakable. It also differentiates from the sibling explain_symbol by clarifying that this tool is for implementation navigation, not documentation or type signatures.

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 when to use the tool ('Use when you need to navigate to the implementation of a symbol') and names the alternative ('For documentation or type signatures at the same position, use explain_symbol instead'). It also provides a clear preference hierarchy: prefer symbol_name over raw line/character positions, with reasoning about avoiding off-by-one errors.

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 thoroughly discloses behavioral nuances: cross-session guard, submodule resolution, fallback refusal, hook execution, and the exact effects of parameters like files and expected_head. No annotations are present, so the description carries the full burden and meets it comprehensively.

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 long but well-structured with clear sections, and every sentence carries meaningful information. Some redundancy exists (e.g., cross-session guard mentioned in both the main text and in confirm/expected_head), but overall it is efficiently organized and not overly verbose.

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

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

Given the complexity of git, the description covers all relevant aspects: subcommand categorization, safety guards, file handling, repo resolution, submodule behavior, and hook execution. It leaves no significant ambiguity about how the tool behaves in various scenarios, making it sufficient for correct agent usage.

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?

Each of the 7 parameters has a detailed description covering usage, examples, side effects, and ignored contexts. For instance, args explains its role for non-add/commit subcommands, files clarifies staged vs path-limited commit semantics, and expected_head details optimistic concurrency behavior. Schema coverage is 100% and enriched with practical examples.

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 git subcommands, categorizes them into read/write/destructive/network, and lists exact subcommands for each, making the purpose unambiguous. It stands apart from sibling tools like git_init which initializes a repo.

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 explains when to use the tool (for git operations) and provides detailed conditions for confirm, expected_head, and repo usage. It implicitly distinguishes from other file-based tools by focusing exclusively on git operations.

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 a key side effect: 'The directory is created if it does not exist', and explains the init_plumb behavior. However, it does not mention whether re-initializing an existing repository is safe, what happens on failure (e.g., invalid path), or any output/return value. This is partial 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 two sentences, front-loaded with the core purpose, and every clause adds value. No wasted words or redundant 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 simple tool with two fully documented parameters and no output schema, the description covers the essential context: what it does, side effects, and the optional flag. It does not mention return values or prerequisites (e.g., git must be installed), but those are minor gaps for a common operation. The description is complete enough for an agent to invoke correctly in most cases.

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 both parameters have detailed descriptions. The description largely repeats the schema: 'path' is the directory to initialize, and 'init_plumb' is explained in the schema and again in the description. The description adds no new semantic information beyond what the schema already provides.

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

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

The description clearly states the specific action ('Initialise a new git repository') and the resource ('at the given path'), with the parenthetical '(git init)' reinforcing the exact command. This distinguishes it from sibling tools like the generic 'git' tool or file-write operations.

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

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

The description implies when to use the tool (when initializing a repository) but provides no explicit guidance on when not to use it or alternatives, such as the sibling 'git' tool. It does not mention exclusions like 'use this only for new repositories' or 'for other git operations use git'. Context is clear but not formally differentiated.

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 fully discloses behavior: it explains the diff response, preview vs. applied change, and the tree-sitter fallback for cold/unparseable files. This goes well beyond the basic write semantics implied by the tool name.

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 tightly-written paragraphs; each sentence conveys a distinct, useful point (use case, content formatting, response behavior, fallback). 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?

Explains the response (unified diff) and edge-case behavior, but does not cover symbol-not-found errors or the dirty_ok workflow beyond the schema, and references an out-of-schema parameter.

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 5 parameters, so the baseline is 3; the description adds value by advising to include a leading newline in 'content' and mentioning a 'show_write_diff' option, though the latter is not in the schema (additionalProperties true).

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 action ('Insert text immediately after a symbol's declaration'), specifies the resource (symbol), and differentiates from siblings like insert_before_symbol and replace_symbol_body by the positional scope.

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 use cases ('adding a new method to a struct', 'appending a related helper') that indicate when to apply it. Does not mention alternatives or exclusions, but the positional 'after' and sibling tools imply the boundaries.

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 fully carries the burden of behavioral disclosure. It covers how symbol location works (LSP document symbol tree), the fallback to tree-sitter when the language server is cold or cannot parse, the response format (unified diff, preview vs. applied), and the effect of include_doc_comment on comment ranges and wrappers. This is rich, actionable 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 a moderately long paragraph, but each sentence contributes distinct, useful information: purpose, use cases, parameter guidance, output behavior, and graceful fallback. It is not as minimal as a two-sentence description, but given the tool's complexity, the length is justified and there is no obvious 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 tool with no output schema and no annotations, the description is remarkably complete. It explains the operation, the location mechanism, the output (unified diff), the dry-run behavior, and the fallback path. It covers the nuanced doc-comment and wrapper behavior, and it even warns about trailing newlines. An agent can select and invoke this tool correctly with high confidence.

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 practical meaning beyond the schema by specifying that 'content' should be the full text with an appropriate trailing newline, that dry_run produces a diff preview, and by elaborating on include_doc_comment behavior (inserting before a doc comment, wrapper handling). It does not add much for uri, dirty_ok, or name_path, but those are already well described 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 opens with a specific verb+resource: 'Insert text immediately before a symbol's declaration.' This clearly distinguishes it from siblings like insert_after_symbol, replace_symbol_body, and safe_delete_symbol, and the use cases ('adding a new function/method... or prepending a doc comment') reinforce the tool's specific purpose.

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

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

The description provides clear context for when to use the tool ('Useful for adding a new function/method before an existing one, or prepending a doc comment') and explains how include_doc_comment changes the operation. However, it does not explicitly name alternatives or state when not to use this tool versus siblings, so it stops short of a perfect 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 provided, the description carries the full burden. It richly discloses delivery semantics (polling, exactly once, via next tool call/check_messages/session_start), session binding, 'silence is not refusal', the thread cap, and the secret-scrubbing requirement. This goes far beyond what the schema reveals.

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 long but every sentence serves a purpose, covering addressing, threads, delivery, permissions, and configuration. The final 'Parameters:' paragraph is partially redundant with the schema, but it also provides a quick-reference summary without bloating the overall structure.

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

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

The description covers nearly all practical invocation details: how to start or reply to a thread, what 'next' means, when re-sending is prohibited, what happens when the thread cap is reached, and the permission/config prerequisites. It even hints at the relevant return payload by saying the reply carries the conversation id, compensating for the absence of an output schema.

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

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

The input schema already describes all three parameters at 100% coverage, so the description's parameter summary adds little new information. It does reinforce the 'reply carries its id' behavior and the omitted-default of 'next', but the schema contains these same nuances. A baseline 3 is appropriate given the high schema coverage.

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

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

The description opens with a specific action — 'Send a message to another agent' — and clearly distinguishes it from check_messages, the receive half. It also names the two addressing modes, 'named peer session' and 'next', so an agent immediately knows what the tool is for.

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 identifies check_messages as the counterpart for receiving, and specifies when to use 'to', when to omit it, and how conversation_id starts or continues a thread. It also covers prerequisites such as cross-project opt-in and the mailbox requirement, leaving little ambiguity about when the tool is appropriate.

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

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

With no annotations provided, the description carries the transparency burden. It discloses meaningful behavioral traits: memories are markdown notes at a specific path, persist across MCP conversations, may have YAML frontmatter used as a one-line summary in the listing, and fall back to the daemon's resolved workspace when 'workspace' is omitted. This goes beyond a basic one-liner, though it stops short of detailing output format or error behavior.

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

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

The description is compact and front-loaded: the primary action appears first, followed by necessary context in short sentences. Every sentence contributes meaning—storage location, persistence purpose, frontmatter behavior, and the default workspace fallback. 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?

For a simple, single-parameter listing tool without an output schema, the description provides the essential context: what is listed, where memories live, how frontmatter influences the listing, and how the workspace default works. It does not describe sorting, error handling, or the exact return structure, but it is sufficiently informative for an agent to 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?

The input schema already fully documents the only parameter ('workspace') with 'Absolute workspace path. Defaults to the daemon's resolved workspace.' The description repeats this same information without adding examples, format details, or edge-case guidance. With 100% schema coverage, the description adds no extra value, 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 opens with a specific verb+resource: 'List memories saved for a workspace.' It clearly distinguishes the listing action from sibling tools like read_memory, search_memories, and delete_memory by focusing on the enumeration of all stored memories. Additional detail about markdown location and frontmatter summaries reinforces the purpose.

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

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

The description explains the memory concept and the default workspace behavior, which implies when to use this tool (e.g., when you need an overview of saved memories). However, it does not explicitly mention alternatives or state when not to use it, such as 'use search_memories to find by content' or 'use read_memory for a single memory.'

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 fully discloses behavior: findings are never blocking, evidence is asymmetric (silence is not proof), confidence is labelled with specific limitations of the topology index (approximate, intra-file, possibly stale), and it degrades cleanly outside git. This exceptional transparency goes beyond typical tool descriptions.

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 dense paragraph, front-loaded with purpose. Every sentence earns its place, but the length and run-on structure make it slightly harder to scan quickly. It could benefit from shorter sentences or bullet-like separation, yet it remains efficient.

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

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

There is no output schema, so the description carries the burden of explaining what to expect. It lists specific finding types, confidence levels, and the meaning of silence, which is substantial. It stops short of describing the exact return structure, but the behavior is well-covered for a review 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 baseline is 3. The description adds practical meaning beyond the schema by explaining `files` scoping in shared worktrees and reinforcing the default behavior of base_ref. This added context elevates the score.

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+resource: 'Reviews a diff for signs of over-building'. It clearly distinguishes itself from siblings by contrasting its deterministic, no-LLM approach with find_references' exact cross-file lookup. The tool's unique role as a non-blocking minimality review is unmistakable.

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 context: reviews working-tree diff vs base_ref, recommends passing `files` in shared worktrees, and notes graceful degradation outside git. However, it does not explicitly name when not to use it or name alternative tools for raw diffs or cross-file reference checking, leaving some inference to the agent.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does this thoroughly: atomicity (all-or-nothing with rollback), dry-run default, undo semantics (per-file, two undo_edit calls), refusal conditions (ambiguous symbol, path outside workspace, Go build-constraint mismatch), and the doc-comment wrapping behavior (ES export wrapper, Python decorator). It even explains the fallback from LSP to tree-sitter. This is exemplary transparency for a mutation tool with zero annotation coverage.

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 dense but well-structured: a clear first sentence stating the core operation, then a 'Scope (v1, conservative)' section for constraints, then a 'Dry-run by default' section for behavior. Every sentence earns its place — the atomicity, rollback, refusal conditions, and undo semantics are all critical for correct invocation. The front-loading of the core operation and the scoped constraints makes it easy for an agent to quickly determine applicability. 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?

For a complex mutation tool with 7 parameters, no annotations, and no output schema, the description is remarkably complete. It covers the operation's semantics (atomic move), constraints (same-directory, refusal conditions), defaults (dry_run, include_doc_comment), edge cases (wrapped declarations, Go package seeding), and post-conditions (undo requires two calls). The only minor gap is the exact return format of the dry-run diff, but the description says 'previews the unified diff' which is sufficient for an agent to know what to expect. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters. The description adds value beyond the schema by explaining the atomicity of the operation, the doc-comment wrapping edge cases (which clarify include_doc_comment), the rollback behavior, and the refusal conditions that affect how parameters like name_path and destination_uri are used. It doesn't add syntax details for the URI formats (the schema already covers those), but it enriches the semantics of the move operation itself. A 4 is appropriate because the description complements the schema without redundancy.

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

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

The description states a specific verb ('Move'), a specific resource ('a top-level declaration... from one file to another'), and precise scope constraints (SAME directory/package, atomic). It clearly distinguishes this from siblings like rename_symbol, insert_before_symbol, replace_symbol_body, and safe_delete_symbol by describing the atomic move semantics and the refusal conditions. The purpose is unambiguous and actionable.

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

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

The description explicitly states when to use the tool (moving a top-level declaration between files in the same directory) and when NOT to use it (cross-directory moves that would change package/import paths are refused; ambiguous symbols are refused; Go build-constraint mismatches are refused). It also names the alternative for disambiguation (name_path) and the dry-run default, giving the agent clear decision criteria. The scope rationale ('plumb-refactor skill') further anchors usage 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 carries full behavioral disclosure. It reveals the compile gate, the restoration guarantee on every exit path with SHA-256 verification, refusals on uncommitted changes and non-green suites, and the meaning of each outcome (KILLED/SURVIVED/INVALID). Nothing is left opaque.

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?

Though long, every sentence adds essential information. The structure is logical: purpose → process → outcomes → scoping → commands → safety → constraints. It is front-loaded with the purpose and each segment earns its place; 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 complex, but the description covers all critical aspects: the exact process, the three outcome meanings, scoping via test_target and topology_affected, the stored command source, restoration guarantees, refusal conditions, and concurrency. It references sibling tools for supplementary info and fully explains the expected behavior even without an output schema.

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

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

Schema coverage is 100%, so the schema already documents all 5 parameters. The description adds significant semantic value beyond the schema: exact-once requirement for old_string, empty-string deletion semantics, the {target} placeholder mechanics for test_target, the unscoped compile_task, and default timeout. This goes well past the baseline 3.

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

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

The description states a specific verb and resource ('Mutation-test your own assertions') and outlines the full process (apply mutant, compile, run tests, classify, restore). It explicitly distinguishes itself from mutant-generating tools and references edit_file for exact-once str_replace semantics, making it clearly distinct 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?

Gives explicit when-to-use (explicit mutants only, not generated) and when-not-to-use (uncommitted changes, non-green baseline, concurrent runs). It names sibling tools for supplementary decisions (topology_affected for scoping, run_task for stored commands) and states the single-run concurrency constraint.

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 and excels: it discloses the cat -n style line-number gutter and warns that it is display-only and must be stripped before reusing as an edit_file old_string. It reveals binary-file rejection, the 200 KiB cap, the header with mtime and SHA-256 for optimistic concurrency, smart-case matching, Go RE2 regex semantics, max_matches default and truncation labeling, and that pattern+limit is rejected. This is exemplary transparency 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?

The description is long but every sentence earns its place, with the core purpose front-loaded. It covers reading, windowing, formatting, output limits, header metadata, search mode, and option interactions in a logical progression. It loses one point for being a dense single wall of text; bullet points or short sections would improve scannability without sacrificing information.

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

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

Given 10 parameters, no annotations, and no output schema, the description is remarkably complete. It explains the return format (line-number-prefixed lines, header with mtime and SHA-256), output limits, binary rejection, search-mode results with context, truncation labeling, and constraint combinations. There is no output schema to lean on, so this description fully compensates; an agent has everything needed to call 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?

Although schema coverage is 100%, the description substantially enriches every parameter. It explains the meaning of the line-number prefix, the search-mode behavior of pattern (literal vs regex, smart-case, case_sensitive semantics), the default and effect of max_matches, context_lines analogized to rg -C, and the mutual-exclusion rules among limit, end_line, start_line, and pattern. This goes well beyond the baseline 3 for high schema coverage.

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

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

The description opens with a clear, specific verb and resource: 'Read the text contents of a file' with accepted path forms (absolute, file:// URI, workspace-relative). It also distinguishes the search-within-file mode from the plain windowing mode, so an agent can tell this tool apart from siblings like read_multiple_files or search_in_files without opening their schemas.

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 for when to use different options: use start_line/end_line to stream slices of large files, use pattern to search within the file instead of windowing, and use line ranges to avoid the 200 KiB output cap. It explains when pattern and limit are mutually exclusive. However, it does not explicitly name sibling alternatives or state when NOT to use this tool in favor of another (e.g., search_in_files or read_multiple_files), so it stops 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.

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

With no annotations, the description carries the full burden and does well by revealing it returns the full markdown content including frontmatter, and names the specific directory. It does not cover error behavior or permissions, but for a read operation this is adequate.

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 primary action, and every word earns its place. It is concise and well-structured.

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 read tool with two well-documented parameters and no output schema, the description is complete. It explains what is returned and provides a usage hint (list_memories first), making the tool fully understandable.

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

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

Schema coverage is 100% and the description adds no additional meaning over the schema. The description only repeats 'by name' and 'workspace' without adding constraints or clarifications beyond what the schema already provides.

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

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

The description clearly states the tool reads a saved memory by name from a specific directory (.plumb/memories/). It uses a specific verb ('read') and resource (memory), and differentiates from siblings by focusing on the 'by name' access pattern.

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 advises using list_memories first to discover available memories, which provides context on when to use this tool. However, it does not mention alternatives like search_memories or read_file, so it lacks explicit 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?

No annotations are present, so the description carries the full burden. It thoroughly discloses important behaviors: reads per file are recorded, individual file errors do not block others, binary files are skipped, the 200 KiB cap applies, paths can be absolute/relative/URI, and strict mode coverage is based on mtime rather than ranges. This is exemplary for a tool missing structural annotations.

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

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

The content is highly relevant and information-dense, but it is delivered as one large continuous block. Some important strict-mode concepts are explained more than once, which adds length without adding new value. The structure would be improved with bullets or labeled paragraphs for read behavior, search/slice behavior, and limitations.

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

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

Given the tool's complexity and lack of an output schema, the description covers all relevant dimensions: path input forms, limits, error isolation, file header output, binary skipping, search syntax, defaults, and strict-mode compatibility. An agent has enough information to invoke and interpret the tool safely.

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%, giving a strong baseline. The description adds meaningful semantic nuance beyond the schema by clarifying uniform application, no per-path overrides, how slicing interacts with read tracking, and how pattern plus start_line/end_line interact. This is valuable but somewhat narrative, so a 4 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–resource statement: 'Read up to 20 files in a single call.' It also distinguishes itself from read_file by emphasizing batched reads, per-file headers, and cross-file parameter application, making its scope immediately identifiable.

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 when to use this tool — multiple files, edit_file under strict mode, and avoiding re-reads. It doesn't explicitly name alternatives such as search_in_files for broader search or read_file for single-file reads, but the intended use case is strongly implied and anchored to read_file semantics.

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 discloses ambiguity handling ('Returns all matches when the name is ambiguous'), the line-number gutter caveat with specific stripping instruction for edit_file reuse, and the tree-sitter fallback when the language server is cold or absent. This goes well beyond basic read semantics, though error cases like symbol-not-found are not explicitly mentioned.

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 four sentences long and front-loaded with the core action. Each sentence adds distinct value: the action, accepted input forms, ambiguity behavior, output format caveat, and fallback mechanism. 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?

For a read tool with no annotations or output schema, the description sufficiently covers return behavior (all matches), ambiguity handling, output line-number gutter instructions, and language-server fallback. The only minor gap is the absence of a symbol-not-found behavior note, but overall it is adequately 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 provides 100% coverage for all three parameters, so the baseline is 3. The description echoes the dotted-name form present in the schema but adds no new parameter-level nuance; it focuses on output formatting and fallback behavior rather than parameter meanings.

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 action: 'Read the source body of a named symbol (function, method, type) in one call,' clearly identifying the resource and scope. It distinguishes itself from siblings like get_definition and read_file by focusing on the symbol body retrieval rather than definition location or whole-file content.

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 through phrases like 'in one call' and accepts plain or dotted forms, but it does not explicitly state when to prefer this tool over alternatives such as get_definition or search_in_files. No exclusions or direct comparison to siblings are provided, leaving the agent to infer the 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?

No annotations are provided, so the description carries full burden. It explains the matching mechanism (frontmatter 'paths:' globs), gives concrete examples of glob patterns, and states the behavioral outcome: 'surfaces only the memories relevant to a given file.' It does not detail return format or edge cases, but given the simplicity of the tool, this is adequate 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 concise and well-structured: first sentence states the core function, second provides context and an example, third gives usage guidance. Every sentence contributes value with 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?

There is no output schema, but the description sufficiently explains the matching logic, the use case, and how it relates to list_memories. It does not verbosely describe return format, but given the memory tools family this is acceptable. The description is complete enough for an agent to know when to use it and what to expect.

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% (both parameters have descriptions). The description adds no parameter-level information beyond what the schema already states; the example glob patterns apply to memory frontmatter, not the tool's parameters. Per calibration, baseline 3 is appropriate when schema covers all 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 what the tool does: 'Return memories whose frontmatter 'paths:' globs match the given file.' It uses a specific verb and resource, and explicitly distinguishes itself from sibling tools like list_memories by emphasizing it returns a much smaller set. This makes the 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?

Provides explicit usage guidance: 'Call this when starting work on a file to discover context the LLM should load before editing.' It also contrasts with list_memories ('much smaller than list_memories when many memories exist'), implicitly indicating when this tool is preferable and hinting at 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 and it delivers: it discloses parent directory creation, overwrite refusal unless overwrite=true, and the LSP FileDeleted/FileCreated side effects that update symbol indexes and diagnostics. The dirty_ok behavior is left to the schema, which is acceptable because the schema describes it fully. It does not mention the return value, but that is a minor gap.

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

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

Four sentences, each earning its place: purpose, parent-directory behavior, overwrite policy plus LSP side effects, and alternative tools. It is front-loaded and free of fluff — a model of concise, high-signal documentation.

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 mutation tool with LSP side effects, the description adequately covers the core behavioral expectations, notes the overwrite safety, and points to alternatives. The schema fills in parameter details (e.g., dirty_ok, from/to formats). It lacks an explicit statement about return value or error behavior, but no output schema exists and the description is still sufficient for safe use.

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

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

The input schema covers all 4 parameters with detailed descriptions, so the baseline is 3. The description adds minimal extra meaning: it restates that parent directories are created and that overwrite is refused unless overwrite=true, both already in the schema. No unique parameter semantics beyond the schema are provided.

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

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

The description opens with 'Move (rename) a file' — a clear verb+resource pair that states exactly what the tool does. It explicitly distinguishes itself from copy_file (duplicates) and rename_symbol (LSP-semantic identifier renames), so the agent knows its unique scope.

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 when-not-to-use guidance: 'To duplicate a file without removing the source, use copy_file instead' and 'For LSP-semantic identifier renames across files, use rename_symbol instead.' This gives clear alternatives and helps the agent select the right 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does an excellent job by covering case preservation, case-insensitive uniqueness checks, reservation of 'next', and the allowance of renaming to the current name. It does not mention side effects like return values or persistence, but the naming-related behavior is thoroughly explained.

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 paragraph of four sentences, all of which contribute useful information. It front-loads the core purpose and then details constraints. It does repeat some schema information, but the added context justifies the length. It is appropriately concise given the complexity.

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

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

The description is complete regarding naming rules and rejection criteria, but it does not mention what happens on success (e.g., return value or confirmation). Since there is no output schema, the description should ideally provide some hint about the result. It also does not state whether the rename affects existing messages or other sessions. This gap prevents a higher score.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining the mailbox analogy, case-insensitivity, and the fact that renaming to the same name is allowed. This enriches the parameter semantics without contradicting 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 starts with 'Renames the current MCP session', which is a specific verb+resource that clearly distinguishes it from sibling tools like rename_file and rename_symbol. It also includes sufficient detail about naming rules to eliminate ambiguity.

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 explains the operation and its constraints, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or situations where other tools would be preferred. The context implies usage (when you need to rename the current session) but lacks 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?

No annotations are present, so the description carries full burden. It discloses atomic edits, dry_run default, response diff preview capped at 20 files, fallback not being scope-aware ('renames every whole-word occurrence'), and dirty_ok behavior. These are concrete behavioral traits beyond the schema's parameter descriptions.

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?

Every sentence earns its place. The description is organized into three focused paragraphs: core semantics, parameter guidance, and fallback behavior. No fluff; even the repeated dry_run reminder reinforces safety-critical information.

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

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

Given that there is no output schema and no annotations, the description fully compensates: it explains the tool's purpose, identification methods, default behavior, response format (per-file unified diff capped at 20 files), fallback conditions, and limitations. For a complex LSP-dependent tool, this is complete enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it specifies symbol_name is preferred over line/character, explains how plumb resolves it through the document-symbol tree, and describes snapping recovery for raw positions. It also clarifies when structural_fallback should be used relative to language server failures.

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 opens with 'Rename a symbol throughout the workspace using LSP semantic refactoring' – a specific verb, resource, and mechanism. It explicitly distinguishes itself from text find-and-replace by mentioning scope/shadowing/type awareness, which differentiates it from sibling find_replace and rename_file.

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

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

Provides explicit usage guidance: 'Prefer symbol_name to identify the symbol', explains when fallback is appropriate ('If the language server cannot compute the rename... pass structural_fallback=true'), and contrasts with find-and-replace ('Safer than text find-and-replace') to aid tool selection. It also notes dry_run default and review-before-apply for the fallback.

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 fully carries the transparency burden. It discloses the LSP range semantics (from 'func' keyword through closing '}'), the orphaned doc comment behavior when include_doc_comment is false, the tree-sitter fallback when LSP is cold, and the unified diff/dry-run response behavior. This is rich, actionable behavioral detail.

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?

Although long, the description is appropriately sized for the tool's complexity. It is front-loaded with the core purpose, then systematically covers usage alternatives, response behavior, fallback modes, and edge cases. Every sentence earns its place; there is no filler or repetition of schema 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 is complete for a complex mutation tool. It covers the diff response and dry-run behavior, the cold-LSP fallback with annotated output, doc comment edge cases including wrappers, and distinguishes itself from related siblings. No output schema exists, but the described return value (unified diff) suffices.

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%, giving a baseline of 3, but the description adds substantial meaning beyond the schema: what 'entire declaration' means, the need to include full signature and body, the doc comment flag's wrapper/export/decorator implications, and the name_path addressing model compared to edit_file. This goes well beyond the individual parameter descriptions.

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

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

The description opens with a specific verb+resource+scope: 'Replace the entire declaration of a symbol with new content.' It clearly distinguishes itself from rename_symbol ('Use rename_symbol if you only want to change the symbol's name') and positions itself for logic/signature changes, making the purpose unmistakable.

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 names alternatives and gives when-to-use guidance: use rename_symbol for name-only changes, use this for logic/signature changes, and contrasts with edit_file's coordinate-based range mode. Also explains when to set include_doc_comment and the wrapper/decorator caveat, providing clear context for decision-making.

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 weight and does so thoroughly. It discloses no shell interpolation, no agent-supplied command line, an OS write-jail sandbox when available, and bounded output/runtime. It also warns about the trust step, which is exactly the kind of behavioral context an agent needs before invoking a command executor.

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 first sentence states the primary purpose immediately, and every subsequent sentence adds a distinct constraint: fixed argv, target placeholder, trust, sandbox, bounded resources, and the run_task alternative. There is no filler or redundancy; the length is justified by the tool's power and risk.

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

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

Given the tool has no output schema and no annotations, the description still tells an agent everything essential to invoke it correctly: what names are valid, how target is constrained, when trust is needed, what sandboxing applies, and when to use a sibling instead. The only omitted detail, exact output formatting, is not needed for correct selection and invocation of a command-runner.

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 fully documents both name and target. The description mostly restates schema facts (allow-list entry, one shell-safe argument, {target} placeholder) rather than adding new parameter-level meaning. It adds useful surrounding context about trust and global config, but that is behavioral context, not new parameter 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 opens with a specific verb and resource: run a named command from the workspace's [[command]] allow-list. It differentiates itself from siblings by stressing the fixed argv model and explicitly pointing to run_task for ordinary build/lint/test work. An agent can distinguish this from write_file, git, or run_task without opening schemas.

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 crisp selection guidance: prefer run_task for routine build/lint/test tasks, and use run_command when a configured allow-list command is needed. It also states the trust prerequisite for project-local commands and notes that global-config commands always run. This tells the agent both when to use the tool and when to pick a sibling.

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

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

With no annotations, the description carries the full burden and is unusually transparent: it discloses trust requirements for project configs, cwd behavior, command provenance, target restrictions, and bounded output/runtime. This gives the agent accurate call-time expectations.

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?

Every sentence adds a distinct non-obvious fact: what is run, trust requirements, cwd, target semantics, and pairing with topology_affected. The core purpose is front-loaded, and the density is justified by the tool's complexity.

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

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

For a side-effecting task runner with no annotations or output schema, the description covers the critical prerequisites: trust, working directory, no arbitrary shell, bounded execution, and relationship to topology_affected. The only notable omission is a precise statement of what the tool returns on success/failure, though 'output and runtime are bounded' gestures at it.

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

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

Schema description coverage is 100%, and both slot and target already have detailed descriptions including allowed values, placeholder semantics, regex restriction, and refusal behavior. The prose description restates this information without adding materially new parameter 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 first sentence identifies a specific action ('Run a stored per-language task command') and a concrete resource ([tasks.<lang>] slots), enumerating build/lint/test/e2e/verify. The explicit contrast 'no shell, no agent-supplied command line' separates it from arbitrary command runners like run_command without ambiguity.

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

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

It clearly states when run_task applies (stored, per-language task slots; paired with topology_affected for which tests to run) and when it does not (no agent-supplied shell command, project configs must be trusted first). It stops short of naming run_command as the alternative for arbitrary commands, but the exclusion is clear 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 fully discloses important behaviors: it calls LSP references, rejects with referencing locations, handles orphaned doc comments, offers dry-run preview, and respects dirty_ok. This gives the agent a complete picture of side effects and safety guarantees.

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 but comprehensive, using four focused paragraphs to cover core behavior, reference check, doc comment handling, and diff response. It is well-structured and avoids unnecessary fluff, though slightly longer than minimal.

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

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

Given the tool's complexity (5 params, no output schema, no annotations), the description covers the essential contextual aspects: safety mechanism, dry-run, dirty_ok, doc comment behavior, and response content. It is thorough enough for reliable invocation, with minor gaps like exact formatting of reference locations.

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 include_doc_comment semantics (orphaned comments) and the diff response tied to show_write_diff, enriching beyond the schema's parameter descriptions without repeating them.

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: 'Delete a symbol's declaration only if it has no remaining references.' This is a specific verb+resource+condition that immediately distinguishes it from sibling tools like rename_symbol or move_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 context: it checks references first and rejects deletion if any exist, preventing accidental removal of used code. It does not explicitly name alternatives, but the behavior is clearly scoped to safe deletion, which is enough to guide appropriate use.

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 numerous behavioral traits: binary file skipping via null-byte sniff, file size limits, glob pruning of sibling directories, smart-case behavior, context lines, output caps, and LSP-based symbol annotation with silent omission. This is exceptionally transparent for 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 dense but well-structured, front-loading the core purpose and mode, then layering exclusions and behaviors. Every sentence adds information, though it is long. It earns a 4 for efficiency despite the length; a 5 would require even tighter phrasing without losing the valuable 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?

For a complex tool with 11 parameters and no output schema, the description covers all critical behaviors: exclusions, binary handling, size limits, smart-case, context lines, output caps, and LSP integration. It also explains defaults and edge cases. Nothing an agent needs to call it correctly is missing, making it complete for its complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining smart-case behavior, the default max_file_bytes value, the 200 KiB output cap, and the LSP caching behavior. It doesn't restate schema descriptions but enriches them with defaults and edge-case behavior, justifying a 4.

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

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

The description states a specific verb ('scan'), resource ('current file contents'), and mode ('literal text by default, regex when use_regex=true'). It clearly distinguishes from shell grep/rg and other search tools by emphasizing project confinement and exclusions. The purpose is unambiguous and differentiates from siblings like workspace_search and find_files.

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

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

Explicitly states when to use this tool ('when you need every occurrence, exact verification, audits, or safe replacement prep') and contrasts with shell grep/rg, noting the confinement to the active project. It also details exclusions (no .git/, node_modules/, build artefacts) and behavior like binary file skipping, which guides selection. This is strong 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the FTS5 vs. grep fallback logic, the ranking bonus for user-authored memories, the 'source=memory-fts' annotation, smart-case behavior, and the effect of 'use_regex' and 'case_sensitive' forcing the grep path. It also reveals the output format for grep ('memory name and line'), making behavior highly transparent.

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

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

The description is longer than a simple one-liner but every sentence adds value, covering the main purpose, fallback mechanics, parameter nuances, and alternative tool guidance. There is minor redundancy (e.g., mentioning 'deterministic grep fallback' twice) and the final 'use workspace_search' sentence could be viewed as slightly repetitive, but overall it is well-structured and information-dense without being overly verbose.

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

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

Despite lacking an output schema, the description adequately covers return values: ranked hits with source annotation for FTS, and memory name+line for grep. It also explains the behavioral nuances of each mode, the conditions for fallback, and the difference from the broader workspace_search tool. For a search tool of this complexity, the description is remarkably 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 schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds extra context beyond the schema by explaining how 'mode' overrides the default choice, why 'use_regex' and 'case_sensitive' force grep, and what the FTS vs. grep distinction means for results. It also clarifies that FTS matches whole tokens while grep matches substrings, which enriches 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 first sentence clearly states the tool's function: 'Search saved memories for a workspace.' It distinguishes itself from sibling tools like workspace_search by emphasizing that it targets the memory-only corpus, and it also differentiates the FTS vs. grep fallback behavior, making its scope explicit.

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 vs. alternatives: 'for ranked discovery across code, docs, AND memories in one call, use workspace_search instead.' It also notes that this tool is 'useful when you don't know which memory contains a piece of context' and is 'much faster than reading every memory.' This provides 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 at all, the description carries the full behavioral burden, and it succeeds. It discloses idempotency ('safe to call multiple times'), the sticky-pin guard and force override, the automatic default flip for resumed sessions, and what the returned packet contains. This gives an agent a faithful model of the tool's side effects and safety characteristics.

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 long, but it is dense and each sentence carries real content: returned fields, workspace pinning, brief mode, idempotency, and the guard behavior. It is front-loaded with the most important instruction ('call this first'). Slight structure improvements (e.g., bullets) would help, but the length is justified for a complex bootstrap 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?

This is a six-parameter tool with no annotations and no output schema, so the description must compensate — and it does. It covers output contents, default behaviors, parameter interactions, edge cases (resumed sessions, no resolved workspace, shared connections), and safety. An agent has enough to invoke it correctly and interpret its 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 schema already documents all six parameters in detail. The description reinforces the purpose of workspace and detail, and adds context about the sticky-pin guard, but it does not meaningfully add new parameter semantics beyond the rich 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 opens with 'Bootstrap tool — call this first at the start of every session' and then enumerates exactly what it returns (workspace path, language, git branch, context file excerpt, memory names, git policy, diagnostics, etc.). This is a specific verb plus resource with a clear one-shot orientation purpose that separates it from all sibling tools.

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

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

The description gives explicit when-to-use guidance: 'call this first at the start of every session.' It also instructs when to pass workspace ('If no workspace is resolved yet'), when to use detail:'brief' ('A subagent that just needs cheap re-orientation'), and when to use force ('deliberately switching THIS connection to another project'). This is unusually 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 takes on full disclosure. It reveals that content is secret-scrubbed, stamped with session/date provenance, indexed, lower-confidence, never displaces user-written memory, counts against retention, and is strictly per-workspace. This goes far beyond basic operational details and sets accurate expectations for side effects and security.

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 longer than average but each section earns its place. It is well-structured, front-loading the main purpose, and then methodically covering when, how, behavioral implications, permission, and parameter semantics. A few redundant phrases (e.g., 'durable, searchable memory' and 'indexed for search') prevent a perfect score, but it is far from wasteful.

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 no annotations, the description covers all needed context: purpose, usage timing, permission requirements, pipeline behavior, retention, discoverability, and parameters. An agent would be fully equipped to decide when and how to invoke 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 describes all three parameters with high coverage (100%). The description essentially restates the schema's parameter details (e.g., summary is a one- or two-line headline, paths are globs). It adds a small example for paths but nothing conceptually new, so the schema remains the primary source of truth. 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, vivid action: 'Hand off what you have just learned to other agents on this workspace as a durable, searchable memory'. It clearly differentiates from siblings (e.g., 'instead of waiting for the idle summary') and identifies the resource (agent-generated memory) and the expected outcome. It also contrasts with user-written memory, which removes ambiguity.

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 when-to-use guidance is provided: 'Use it after you have mapped a subsystem, pinned down a gotcha, or worked out how something fits together'. It also gives a when-not-to-use by saying 'instead of waiting for the idle summary to fire', and includes a hard prerequisite ('Requires [collab] knowledge_handoff = true'). This effectively covers both timing and alternatives.

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

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

With zero annotations provided, the description carries the full burden — and it excels. It discloses that the operation is 'ADVISORY and a CLAIM, not a lock', idempotency (one live intent, calling again replaces it), expiration and session-clearing semantics, the polling/hint-injection delivery guarantee, the config gating requirement, and the 'secret-scrubbed before storage' security behavior. This is exactly the behavioral disclosure an agent needs and far beyond what annotations would have given.

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?

Excellent front-loading: the first sentence is a model of purpose communication. But the body is dense and repetitive — the 'unverified claim' / 'claim' concept appears three times, 'workspace_sessions' twice, and jargon like 'plumb does not push' is unexplained, which will cost an agent comprehension time. The trailing parameter section duplicates the schema with minimal extra info. Well-organized but overstuffed for what could be 40% shorter.

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 the absence of annotations and output schema, an agent has everything required to call this correctly: preconditions, single-live-intent semantics, TTL defaults and overrides, session life-cycle behavior, peer-visible effects, and security handling. Given the tool's complexity — stateful, cross-agent, security-sensitive — there are no obvious informational gaps an agent would trip over.

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 a helpful concrete glob example ('internal/tools/ratelimit*') and connects path_globs to the 'drives peer write hints' behavior that the schema implies but doesn't state. However, the 'Parameters:' section in the description largely restates what the schema already documents, so the net new value is incremental rather than transformative. A 3 is the right call.

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

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

Starts with a specific verb+resource: 'Broadcast what you are working on to other agents active on this workspace RIGHT NOW'. The 'steer around... instead of colliding' phrase gives the operational outcome, and the example ('refactoring the rate limiter') grounds it immediately. Even without reading siblings, an agent can tell this broadcasts intent for coordination rather than persisting or recalling data.

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 contrasts the tool with the sibling 'workspace_sessions' recent_writes, and states when the call is refused ('Requires [collab] intents = true'). It also clarifies the delivery model ('polling and hint injection only'). Minus one because it never names a sibling for the alternative case (e.g., persisting memory or checking messages), so an agent must infer when NOT to use it from the single workspace_sessions comparison.

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 that results are approximate (source=topology), confidence-labelled for heuristics, that no raw tree-sitter queries are exposed, and that a clear message appears when the index is disabled or empty. This is comprehensive behavioral disclosure.

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

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

The description is front-loaded with a clear purpose, uses a single well-structured paragraph, and every sentence adds value—from sibling differentiation to query examples to behavioral caveats. 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?

For a 4-parameter tool with no annotations or output schema, the description covers purpose, usage, alternatives, behaviors, parameter details, and an edge case (disabled/empty index). Missing are the general return format and permission requirements, but these are less critical for a read-style 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 baseline is 3, but the description adds significant meaning beyond schema fields: it explains the named query options with concrete definitions (undocumented-exports, long-functions, unused-context), notes that unused-context is Go-only, and clarifies the default for min_lines. This extra context elevates the score.

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 begins with a specific verb+resource combination ('Run a curated structural check over the topology index') and explicitly contrasts with sibling tools ('Complements topology_search (find by name) and search_in_files (find by text)'). It clearly distinguishes the tool's shape-based search purpose from name- or text-based alternatives.

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

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

The description names the primary alternatives and explains the tool complements them by providing structural audits useful for review and refactor prep. While it doesn't exhaustively list every possible 'when not to use' scenario, the contrast with topology_search and search_in_files gives clear 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 behavioral burden, and it succeeds: it discloses the heuristic nature of results, the deliberate recall bias (counting every test in a reached package), the cross-package import edge rule, language-dependent command formatting, and the behavior when topology is disabled. This is exemplary transparency for a complex 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 long, but it is front-loaded with the core purpose and every subsequent sentence adds necessary operational detail (output shape, path handling, reachability rules, cap behavior). It could be tightened with bullet points, but it avoids fluff and each clause 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?

Given the tool's complexity, the absence of an output schema, and the absence of annotations, the description is remarkably complete. It covers input expectations, output structure, per-language command behavior, recall bias, heuristics, max_results semantics, ordering guarantees, and failure mode when topology is disabled. An agent has enough information to invoke and interpret the result 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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: files and symbols are "change roots," max_results bounds PACKAGES rather than test rows, and the changed package is always sorted first so a cap cannot drop it. This goes beyond what the schema descriptions already state.

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 concrete use case: "After you change code, ask this which tests to run instead of running the whole suite." It names a specific resource (affected PACKAGES) and a specific output (packages with test counts, reasons, and individual test names), which clearly distinguishes it from siblings like topology_status, topology_search, and topology_impact.

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

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

The description gives clear context for when to use this tool — after code changes, to select tests rather than run everything. It implies the alternative (running the full suite) but does not explicitly name other topology or test-selection tools or state when not to use it, so it stops short of full 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 behavioral burden and does well. It discloses that source is approximate, returns an error when topology is disabled or symbol missing, reports truncation when limits hit, and explains how max_bytes truncates on symbol boundaries. It doesn't mention rate limits or performance, but for a read-only exploration tool, it covers the key behavioral aspects.

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 dense and informative, but moderately long. It front-loads the purpose and immediately provides usage maxims, followed by behavioral notes. Some redundancy with the schema (like repeating default values) adds length but not much cost. It earns its place overall, though a tighter version could trim the default value 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?

For a complex tool with 8 parameters and no output schema or annotations, the description is remarkably complete. It covers the return content (centre node, neighbour nodes, edges), truncation behavior, error conditions, approximation caveat, and parameter tuning guidance. The output schema would further help, but given the constraints, an agent has enough 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 baseline is 3. The description goes beyond the schema by explaining the relative cost of include_source options (signatures is 'several times larger' than none) and providing example combinations (depth=1 with max_nodes=15), which helps agents choose values strategically. It does not describe relationship between edge_kinds and output, but the schema already lists valid kinds.

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 performs a bounded BFS neighbourhood exploration around a named symbol in the topology index, with a specific resource and operation. It is distinguished from siblings like topology_search or find_references by the explicit neighbourhood/BFS focus, though it doesn't name a direct sibling for contrast.

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: 'NARROW IT FIRST on a large file or an unfamiliar language', recommends specific parameter values (include_source='none', depth=1, max_nodes=15) for quick 'what touches this?' queries, and advises raising limits 'once you know what you are looking for'. Also notes caveats such as topology being approximate and recommending LSP semantic tools for authoritative lookups.

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, and it excels: it discloses that the topology source is approximate and intra-file, that cross-file callers come from the language server when available, that unsupported/polyglot workspaces are refused rather than falsely reported, and that every output discloses limitations and is byte-capped. This is unusually rich behavioral disclosure.

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 long, but the tool is complex with 12 parameters and no annotations. Almost every sentence contributes distinct information about modes, sources, limitations, or failure behavior. It would benefit from tighter paragraph separation, but it remains well above a minimal viable description.

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 no output schema and no annotations, the description covers the input modes, granularities, edge kinds, source limitations, cross-file resolution, failure messages, and disclosed scope. An agent has enough context to decide when and how to invoke it and what to expect in return.

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%, but the description goes well beyond the schema by explaining the meaning of granularity, roots, mode, and path_to in operational terms. For example, package granularity is tied to 'production import edges from package-main roots plus candidate-seeded topology_routes roots', and function granularity is tied to an 'admitted Go-only partial static call graph' with exact callable roots.

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 immediately pins down the behavior: 'Bidirectional BFS blast-radius analysis around a named symbol' and explicitly names the two output sections. It is clearly distinct from sibling topology tools like topology_search or topology_explore because it frames itself as blast-radius analysis for refactoring.

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 the primary use ('assess blast radius before a refactor') and explains when to switch modes and granularity, including Go-only and reachability constraints. It does not explicitly name sibling tools as alternatives, but the context is clear enough for an agent to choose it over related topology 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?

There are no annotations, so the description carries the full behavioral disclosure burden. It fully meets that burden: it discloses that no route registrations or call sites are parsed, that results are candidates rather than confirmations, that each candidate carries a confidence annotation, and that a clear 'no match'/disabled message will be returned. This is exemplary transparency for a tool with no structured annotations.

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

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

The description is informative and mostly well-structured, opening with the core function and then bounded by scope limitations and result semantics. Some redundancy exists: the 'no route registration parsing' point is stated multiple times, and 'candidates, not confirmed routes' is also echoed in slightly different wording. Still, the key constraints are front-loaded and readable.

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 parameter-light, no-output-schema tool, the description covers the modeling intent, negative scope, result semantics, confidence annotations, and failure behavior. The main gap is that it does not describe the exact snapshot of the return value beyond candidates and message, which would matter more given that there is no output schema. Overall, though, an agent can call this tool with clear expectations.

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 fully documents `limit`, `framework`, and `path_prefix`. The description mainly restates what the schema provides, including the caveat that `path_prefix` is not a URL path filter. It adds no significant new meaning beyond the schema, 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 specifies what the tool does: it pattern-matches entry-point-shaped symbol names and signatures, with concrete examples across Go, Python, and Swift/Vapor. It also draws an explicit boundary by stating what it does NOT do — parse route registrations or resolve path-to-handler bindings. It does not name a sibling tool as a direct alternative, but the scope is concrete enough to be distinguishable.

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 strong usage guidance: use this tool to find entry-point-shaped candidate functions, not to recover confirmed route bindings. It clarifies that results are unconfirmed candidates and that path_prefix is not a URL path filter. However, it does not explicitly point to an alternative sibling tool (e.g. a route-resolution or topology-search tool) for cases where the user needs actual parsed route mappings.

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 bears the full burden of behavioral disclosure. It conveys that the source is approximate ('topology (approximate)'), explains the return fields (kind, file path, line range, match field, score, optional snippet), and mentions a clear message when the index is disabled or empty. It does not mention side effects (none for a search) but adequately covers the operational 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 reasonably concise, with each sentence delivering distinct value: it states purpose, provides usage guidance, lists result fields, and gives alternative tooling. The key 'Narrow a broad query first' instruction is front-loaded. It's slightly long but not verbose, earning a 4 rather than a 5.

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 is complete for a search tool: it specifies the result structure, explicitly notes the approximate nature of the source, and covers the disabled/empty index behavior. Since there is no output schema, the description properly explains return fields. It also references sibling tools for alternative use cases, making it self-sufficient 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?

Schema coverage is 100%, so the schema already fully documents all parameters. The description adds minor guidance (e.g., suggesting include_snippets=false to narrow) and clarifies the re-rank behavior, but it does not add substantial meaning beyond what the schema provides. A baseline of 3 is appropriate when the schema is the primary source of parameter information.

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

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

The description clearly states a specific verb (search) and resource (topology index), and explicitly distinguishes itself from search_in_files (exact filesystem matches) and workspace_search (broader discovery including docs and memories). It also lists what it finds (symbols, functions, types, classes) and the fields returned.

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 opens with 'Narrow a broad query first', gives specific narrowing parameters (kinds, language, limit, include_snippets=false), and explicitly tells the agent when to use alternatives: 'use search_in_files for exact filesystem matches' and 'for ranked discovery that also spans docs and memories, use workspace_search'. This provides 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 full burden. It discloses that the tool reports information and returns a clear message when indexing is disabled, which is a behavioral trait. It does not mention potential side effects, errors, or performance implications, but the verb 'Report' implies read-only behavior, and the listed outputs are transparent. Some details about failure modes remain unspecified.

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, with the main verb 'Report' front-loaded. It lists all relevant output items without fluff or repetition. The conditional 'Returns a clear message when disabled' is a concise, structured addition. No 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?

The tool has no output schema, so the description must explain the return values. It enumerates the statistics (indexer state, counts, reasons, nodes/edges, db size, sync time, languages, error) and the disabled-case message, which is sufficient for an agent to know what to expect. It does not specify the exact format or types, but that is not strictly required. Minor gap: no mention of error handling in exceptional situations.

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 parameter 'workspace' is fully described in the input schema (absolute path, defaults to session workspace). The tool description does not add any additional meaning or context for this parameter, so it does not go beyond the schema. Since schema coverage is 100%, the baseline score of 3 applies.

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

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

The description clearly states the tool's function: reporting the health and statistics of the topology index. It lists the specific information returned (indexer state, counts, nodes/edges, db size, etc.) and mentions the disabled-indexing case. This distinguishes it from sibling tools like topology_search or topology_explore, which are clearly about querying rather than status reporting.

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

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

The description does not explicitly state when to use this tool versus alternatives, such as 'use this to check if the index is up-to-date' or 'use topology_search for querying.' However, the purpose is self-evident from the report content, and the disabled-indexing fallback hints at a diagnostic role. Still, explicit guidance on when to choose this over siblings 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?

The description thoroughly explains the behavior: validation against on-disk content, all-or-nothing write semantics, rollback on partial failure, and locking. Since no annotations are provided, the description carries full responsibility for transparency, and it does so completely without 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 concise, using three sentences to convey purpose, behavior, and usage context. It is well-structured and free of redundancy, with each sentence contributing essential information.

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

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

The description covers the core aspects: what the tool does, how it ensures atomicity, the locking mechanism, and the intended use case. It also mentions the 50-operation limit. Since no output schema is present, explaining return values is not required, and the description is complete for an agent to decide and invoke correctly.

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

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

The schema already provides 100% coverage of parameter descriptions, so the baseline is 3. The description does not add further semantic meaning to the parameters; it mentions atomicity and locking but does not elaborate on await_diagnostics or fail_on_new_errors beyond what the schema states. Thus no extra value is added.

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 (apply str_replace edits), the resource (multiple files), and the key property (atomically). It also distinguishes this tool from others by mentioning per-path locks and the use case for refactors that must land as one unit, making it easy to tell apart from sibling tools like edit_file or write_file.

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

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

The description explicitly states when to use this tool: 'Use for refactors that must land as one unit.' It also contrasts with other write tools by noting per-path locks prevent interleaving, implying it is preferred for multi-file atomic operations. This gives clear guidance on 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?

No annotations are present, so the description carries the full burden. It discloses important behaviors: identifier positions are resolved by plumb to avoid off-by-one errors, and positions off an identifier are snapped to the enclosing symbol. It does not mention read-only status or potential errors, but the transparency provided is meaningful.

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 and well-structured: first sentence defines what it does, second explains parameter preference, and third gives the use case. Every sentence contributes necessary information with 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?

The description covers core purpose, parameter selection, and use case, while the schema fully documents all parameters. The main gap is the lack of output format (e.g., whether it returns a tree or list), which is somewhat important given there is no output schema, but the description is still adequate for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining why symbol_name is preferred over line/character, describing off-by-one risks, and the snapping fallback. This enriches the parameter semantics 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?

The description clearly states a specific verb and resource: 'Show the type hierarchy for a type' and elaborates with concrete definitions of supertypes and subtypes. It implicitly distinguishes from siblings like call_hierarchy by focusing on inheritance/embedding relationships rather than call relationships.

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 when to use the tool ('Useful for understanding inheritance and polymorphism') and provides usage guidance on preferring symbol_name over line/character to avoid off-by-one errors. However, it does not explicitly name alternative sibling tools or state when not to use 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?

With no annotations provided, the description fully carries the burden and excels: it discloses the refusal default, force override, file-creation removal, single-level undo behavior, per-session history clearing, and the 1 MiB snapshot limit. This gives the agent a complete mental model of side effects and constraints.

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 dense paragraph, but every sentence earns its place: main purpose, safety comparison, refusal behavior, force override, creation removal, re-arm behavior, session scope, and size limit. It is front-loaded with the primary action and logically organized from common to edge cases.

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 is a moderately complex tool with no output schema and no annotations, yet the description covers all essential behavioral aspects: what it undoes, safety guards, force semantics, file lifecycle, undo depth, session lifetime, and availability limitations. It is complete enough for an agent to correctly decide when to call it and predict outcomes.

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, but the description adds meaningful context for `force` by elaborating when and why to use it (to override refusal after external edits) and warns about the 1 MiB limit affecting undo availability. It does not add much for `file_path` beyond the schema, but the added force context 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 opens with a specific action and resource: 'Revert plumb's most recent write to a file.' It clearly distinguishes itself from `git checkout <file>` by framing it as the safe alternative, and the detail about restoring only plumb's last edit removes ambiguity about scope.

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 names `git checkout <file>` as an alternative and explains the safety tradeoff, giving clear context for when this tool is appropriate. It also describes refusal conditions (file modified since, no snapshot over 1 MiB), but does not explicitly state 'use this instead of X when...' or cover scenarios like undoing multiple edits, so it stops short of full usage-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?

No annotations are provided, so the description carries full burden. It discloses approximate ranking, non-exhaustiveness, result labelling (corpus, source, field, score, why matched), per-corpus freshness headers, and that exact_match is always false.

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

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

Three sentences, purpose-first, no wasted words. Each sentence adds distinct value: scope, usage guidance, and result behavior.

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

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

With no output schema, the description explains return structure and freshness reporting. It also covers limitations (approximate, no proof of absence) which is important for a search tool.

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

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

Schema covers all three parameters with helpful descriptions. The description adds context about FTS5 ranking and interleaving, clarifying how query and corpora behave beyond the schema's basic 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 opens with 'Ranked discovery across the workspace's indexed corpora: code symbols, doc sections (Markdown/HTML), and project memories' – a specific verb and resource scope. It also names the sibling tool search_in_files as the alternative, establishing clear differentiation from other search 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?

Explicitly states when to use: 'Use workspace_search when you have a conceptual question...' and when not to use: 'Approximate by design and never a proof of absence — the exact lane is search_in_files.' Names the alternative tool and gives an example query.

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