borer

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

Annotations already establish that this is a read-only, closed-world operation, and the description does not contradict that. The description adds useful behavioral context beyond annotations: results are session-scoped ('added this session'), paged, and focused on comments opening with '?'. It does not describe ordering or default paging behavior, but the core behavior is clear.

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 two-sentence description is front-loaded with the core purpose and immediately follows with usage guidance and exclusions. Every clause carries useful information without 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 read-only listing tool with fully documented parameters, the description covers purpose, session scope, paging, and alternatives adequately. It could be slightly richer about return contents or ordering, but no critical information is missing 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 description coverage is 100%, so all four parameters are already documented in the schema. The description mentions paging but adds no syntax or default details beyond what the schema provides, making baseline 3 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 gives a specific verb (List) and concrete resources (names, findings, and open-question comments added this session), plus paging behavior. It also distinguishes the tool from sibling tools `symbols` and `types`, so an agent can identify it without inspecting the schema.

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

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

It explicitly states the intended use case ('Use it to resume work') and names the alternatives for out-of-scope cases ('not for binary symbols (use symbols) or user types (use types)'). This is 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's added value is the precondition/error behavior ("Fails if nothing is loaded") — a concrete failure mode the agent must sequence around. It adds real context beyond the annotations, though it says nothing about output size or cost of the entropy computation.

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

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

Two tight sentences: the return contents are front-loaded, followed by workflow guidance and the failure condition. Every clause carries information; no filler.

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

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

With no parameters, no output schema, and annotations already covering the safety profile, the description's enumeration of returned fields plus the load precondition and the triage hand-off make the tool callable 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?

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies no input is needed.

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

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

States a specific verb ("Summarize") and resource ("the loaded program") and enumerates exactly what is returned: format, arch, entry, sections with entropy, imports, exports. An agent can distinguish this from siblings like entropy, symbols, or strings without opening a schema.

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

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

Explicitly routes the agent elsewhere for adjacent needs ("for protection and where to start, query borer://triage") and names the prerequisite producer (load_binary). The "load_binary already returns it" clause is slightly ambiguous about whether this tool is redundant after a load, which keeps it from 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral detail: mermaid output, imports appear as leaf nodes, and a %% comment line reports nodes dropped by max_nodes — telling the agent how truncation is surfaced rather than silent. It stops short of describing overall response shape or pagination, keeping it at 4.

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

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

A single dense sentence plus one exclusion clause; the primary behavior and output format are front-loaded and every clause carries information (direction, leaf handling, truncation marker, alternatives).

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 takes on the burden of describing the return value and does so (mermaid text, imports as leaves, %% truncation line). Combined with annotations covering read-only status, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by explaining the semantic consequence of callers=true (inverted traversal) and, importantly, that exceeding max_nodes produces a %% line counting the cut nodes rather than an error. That truncation contract is not 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?

States a concrete verb (draw), resource (a function's call graph), and output format (mermaid), plus the direction switch via callers=true. It explicitly names the sibling tools it is not (reaches, xrefs), so an agent can distinguish it 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?

Provides explicit exclusions with alternatives: 'Not for one path (use reaches) or a caller list (use xrefs).' This is the when-not/use-instead guidance pattern, requiring no inference from 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds meaningful output behavior beyond annotations: mermaid text with blocks and successor edges, pagination at 300 blocks per page, and a '%% line when cut' truncation marker. It does not describe every edge case, but it substantially enriches the behavioral picture.

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

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

Two tightly packed sentences with zero waste. The core action and output format are front-loaded, followed by pagination/truncation details and then explicit tool alternatives. 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 read-only CFG visualization tool, the description covers purpose, output format, pagination behavior, truncation signaling, and when to use alternatives. Although there is no output schema, the mermaid return format is described sufficiently for correct invocation. 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 both parameters are already documented: 'offset' is blocks to skip at 300 per page, and 'address' is a function entry or any address inside it. The description repeats the '300 blocks a page' pagination but adds no new parameter semantics beyond the schema. 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?

States a specific verb and resource: 'Draw a function's control-flow graph as mermaid'. It also explicitly distinguishes itself from two sibling tools by naming what it is not for and pointing to 'decompile' and 'function'. An agent can identify the right tool 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?

Provides explicit exclusions and alternatives: 'Not for reading logic (use decompile) or a block table (use function).' This directly says when to use this tool versus others, leaving little inference.

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

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

Annotations establish it is a non-read-only, non-destructive, idempotent operation; the description adds the key behavioral detail that apply=Name materializes a struct and that it is only a dry run until dry_run=false, which is not derivable from annotations. It stops short of covering what happens if the struct name already exists or what the inference output looks like.

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

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

Two dense sentences, front-loaded with the core inference capability, then the sibling exclusion, then the write gating. No filler.

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

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

No output schema exists, but the description enumerates what is inferred (offset, width, reads, writes) so the agent knows what comes back. Missing only edge-case behavior for re-applying over an existing struct definition.

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 still adds value by tying apply and dry_run together into a single save-vs-preview rule, clarifying behavior the schema's terse 'false applies' phrasing leaves ambiguous. The 'class' parameter accepting a method address is covered by the schema, not the description.

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

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

States a specific verb (infer) and precise resource (a C++ class's fields, methods, vftable) plus the evidence basis (offset, width, reads, writes). It also names the sibling it is not (set_type) so the agent can distinguish it 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?

Explicitly scopes use to unknown classes and routes the known-layout case to set_type. The alternative and the selecting condition are both stated outright.

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 readOnlyHint and openWorldHint already covering the safety profile, the description instead spends its words on non-obvious output semantics: local_N/arg_N naming with hex byte offsets, /* asm */ for unmodeled code, line 2 as a check summary, and // warn: for problems. It does not mention failure modes (e.g., functions that cannot be decompiled) or output size expectations, which keeps it just short of the top score.

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 tight sentences, front-loaded with what the tool does, then the decoding conventions an agent needs to read the output. Nothing is redundant with the schema or 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?

There is no output schema, so the description carries the burden of explaining the returned text, and it largely does via the naming scheme and marker conventions. What's missing is only edge-case behavior, such as what a failed or partial decompilation looks like, which is a minor gap for a read-only single-function tool.

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

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

Schema description coverage is 100% and all five parameters (address, limit, detail, filter, offset) are already documented in the schema, so the baseline of 3 applies. The description adds no parameter-level guidance such as when to prefer skeleton over full or how filter interacts with limit.

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

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

States a specific verb and resource ("Decompile one function to pseudo-C") with an explicit unit-of-work (one function). The closing clause distinguishing it from function_summary lets an agent separate it from the summary sibling without opening either schema.

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

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

Gives an explicit exclusion and a named alternative: "Not for a first look (use function_summary)." The positive trigger is only implied by "one function," and alternatives like disassemble_function or decompile_batch for multiple functions are not mentioned, so routing is clear but not exhaustive.

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

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

Annotations already declare destructive=true, readOnly=false, idempotent=false, and closed-world behavior, so the bar for extra disclosure is lower. The description still adds useful operational context: parallel execution, per-function and total character caps, and file persistence semantics ('kept unless overwrite=true'). It does not add auth or rate-limit details, but those are less central here.

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 verb and resource, and every clause carries operational detail. The semicolon-heavy first sentence is dense but not wasteful, and the single-function alternative is placed clearly at the end.

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 five-parameter tool with full schema coverage and annotations, the description covers the important behavioral complexities: parallel batch decompilation, character caps, file output, overwrite semantics, and the single-function alternative. Remaining details such as exact return formatting are minor and partly handled by the schema and annotations.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds meaning beyond the schema by clarifying output capping and that out writes uncapped results to a file; this is useful for understanding the out/filter/max_functions interaction even if it does not restate every parameter.

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

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

States a specific verb and resource ('Decompile many functions') and explicitly names the single-function sibling ('For one use decompile'), making the distinction from decompile clear. It also adds the name-filter matching condition, so the tool's purpose is 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?

Gives the key alternative for a single function and explains the out=<file.c> mode for uncapped bulk output versus the capped default behavior. It stops short of stating explicit exclusions such as out not combining with filter or max_functions, leaving those constraints to the schema.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds a meaningful failure mode ('fails if unmapped') and the result format, which go beyond the annotations. It stops short of stating pagination/truncation behavior beyond what the schema's count max implies.

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

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

Three short sentences, zero waste, with purpose and output format front-loaded before the usage routing and failure note.

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 3-parameter tool with no output schema, the description covers what it returns (VA/text rows), when to use it, and the unmapped-address failure. Only minor gaps like output volume/limits remain, and those are partly handled by the schema's max.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description only implies that count controls instruction count and that address accepts VA or symbol; it adds little syntax beyond the structured fields, so the baseline of 3 applies.

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

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

States a specific verb (disassemble) with a scoped resource (count instructions from any address) and names the output shape (`va text` rows). It explicitly contrasts with the sibling disassemble_function, so an agent can pick between them without opening either schema.

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

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

Gives an explicit when-to-use (a few instructions, or code outside functions) and an explicit alternative for the other case (whole function → disassemble_function). No inference required.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: output is organized into blocks with address labels and resolved call target names, which is the key expectation for callers. It omits truncation behavior, though the max_instrs cap is documented in 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?

Two sentences, front-loaded with the verb and output shape, then the routing rule. Nothing redundant and nothing padding.

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 three-parameter tool with full schema coverage and no output schema, the description covers what the tool does, how output is shaped, and when to prefer siblings. It could note the instruction cap consequence (truncated results for large functions), but that is already in the schema.

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

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

Schema description coverage is 100%, and all three parameters (bytes, address, max_instrs) carry their own defaults and limits in the schema. The description adds no parameter-level meaning beyond noting whole-function scope, so the baseline 3 applies.

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

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

States a specific verb (disassemble) plus resource and scope (a whole function by blocks) and even characterizes the output format via `L_<addr>:` labels and named call targets. That distinguishes it from the sibling `disassemble` (few instructions) and `decompile` (C output).

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 both alternatives and the conditions that select them: exact instructions → this tool, C code → decompile, a few instructions → disassemble. The agent has no inference left to make about tool 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is known; the description adds genuinely new behavior: results are capped at 200 rows and paged, and each row has a fixed column layout. It stops short of explaining how the window setting affects detection sensitivity or what an empty result implies, which is a minor gap against an otherwise solid 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?

Two dense sentences: the detection criterion and result format come first, the disambiguation and cap follow. There is no filler, and the output row layout is conveyed compactly rather than as prose.

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

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

With no output schema, the description carries the burden of describing return values, and it does so at least partially via the `off va len entropy` row format plus the 200-row paging note. What's missing is guidance on tuning window versus threshold, which matters for a heuristic scanner whose results depend heavily on those two defaults.

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 limit, offset, window, and threshold are all documented in the schema, which sets the baseline at 3. The description reinforces the threshold concept ('at or above threshold bits/byte') and the 200 cap but adds no syntax or tradeoff guidance beyond that, so it does not earn 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 gives a specific verb ('Find') and a precise object ('packed, compressed or encrypted data'), then defines the detection criterion (chunks at or above threshold bits/byte) and the output shape (`off va len entropy` rows). It also distinguishes itself from the naming step by pointing at borer://protection, so an agent can tell exactly what this tool answers.

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

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

It states the triggering condition (looking for packed/compressed/encrypted regions) and redirects the packer-identification sub-task to borer://protection. It does not, however, contrast with adjacent detection tools such as find_crypto_constants or strings, so routing among the analysis siblings is only partly resolved.

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

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

Annotations already declare openWorldHint=true, idempotent=true, destructive=false, so the network-write profile is partly covered. The description adds real value on top: the source servers (BORER_SYMBOL_SERVER or Microsoft's), the https transport, the GUID/age validation gate, and the dry-run default. It does not cover failure modes (GUID mismatch, download errors) or cache location, so not a 5.

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

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

Two sentences, no filler. The core action and cache rule come first, the when-to-use and workflow follow, and the dry-run constraint is placed where an agent needs it before invoking.

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 one-parameter, no-output-schema tool with helpful annotations, this covers what it does, when to call it, and what to do afterward. Minor gaps remain around what happens on GUID mismatch or download failure, but nothing essential to a correct call 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?

With 100% schema coverage on the single parameter, the schema already explains dry_run's default and effect. The description only reinforces the default with 'dry run until dry_run=false', which is procedural rather than new semantic detail, so baseline 3 applies.

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

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

States a specific verb and resource: downloads the missing PDB for the loaded PE, over https, into the cache. It also states the retention rule (kept only if GUID and age match), which separates it clearly from siblings like load_binary and symbols.

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 trigger: 'Use it when load_binary reports no PDB'. Explicit sequence: dry run first, set dry_run=false, then re-run load_binary. Both the when and the surrounding workflow are named with a sibling 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?

Annotations already declare this as a read-only, closed-world search. The description adds useful behavioral context beyond the annotations: it describes the output row shape (`va section algorithm`) and that results are paged. It does not cover rate limits or empty-result behavior, but for a read-only search tool this is largely 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 two dense, front-loaded sentences with no filler. The core purpose and output format come first, and the usage workflow and alternative follow immediately.

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 two-parameter read-only search tool with no output schema, the description supplies the missing output shape (`va section algorithm`), paging behavior, and a follow-up workflow (xrefs a hit). An agent has enough information to select and call it correctly.

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

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

Schema description coverage is 100%, so `limit` and `offset` are already fully documented in the schema. The description adds only that results are 'paged', which is marginal additional meaning beyond the schema's own 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?

States a specific verb and resource: find crypto constants and tables. It lists concrete algorithm examples and describes the row format (`va section algorithm`), making the tool's scope and output shape clear. It also distinguishes itself from `strings` by explicitly excluding string searches.

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

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

Explicitly says to use it to locate crypto code and then xrefs a hit, and warns not to use it for strings (use `strings` instead). This gives clear when-to-use guidance and names an alternative tool for a likely confusion case.

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

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

Annotations already declare `readOnlyHint: true` and `openWorldHint: false`, so the safety profile is covered. The description adds useful behavioral context: case-insensitive matching, paged output, and the shape of the returned string legend and function rows.

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 sentence plus one routing sentence, with the core action front-loaded. Every clause contributes either purpose, output shape, or disambiguation.

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 explains the return format and paging behavior. Combined with full parameter schema coverage and annotations covering read-only status, this is sufficient 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?

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description's mentions of case-insensitivity and paging are mildly reinforcing but largely redundant with the schema's own 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 states a specific verb and resource: find functions whose strings contain a text, case-insensitively. It also distinguishes the tool from sibling `function_strings` and gives a compact indication of its output shape.

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 what the tool is not for — one function's strings — and names the correct alternative, `function_strings`. This directly resolves the most likely sibling ambiguity an agent would face.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds the block-table column format (`start size term successors`) and the 300-blocks-per-page pagination behavior, which are genuine behavioral details not in the annotations. It stops short of saying what happens at the end of a function with more than one page or how the paging interacts with callers/callees.

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

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

Two sentences, both earning their place: the first defines content and pagination, the second routes to the alternative. Front-loaded with the resource and the notable format detail.

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

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

No output schema exists, so the description must carry the return shape — it does so by enumerating the fact categories and the block-table columns, plus pagination. Minor gaps remain (total block count, behavior when a name resolves to multiple functions), but nothing essential to a correct call 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 both parameters are already documented — including the flexible "entry, any address inside it, or a name" semantics for address and the skip-count for offset. The description only restates the 300-per-page figure already present in the offset description, adding no new param-level meaning.

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?

Specific verb ("Show") plus resource ("one function") and an explicit inventory of the returned facts — range, counts, callers, callees, block table. It also names the sibling it is not, so an agent can distinguish it from function_summary without opening either schema.

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

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

Explicitly states the negative condition ("Not for a readable triage") and names the alternative tool that should be used instead (function_summary). The positive case is implied by "raw facts", and the routing rule is unambiguous.

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

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

The annotations already establish that this is a read-only, closed-world operation. The description adds useful behavior beyond that by stating the tool is paged and by documenting the exact returned row columns, which helps the agent understand the response shape without an output schema.

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

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

The description is compact and front-loaded with the most important information: what is listed, the row shape, paging, filtering, sorting, and the sibling exclusion. Every clause carries useful 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?

Even though there is no output schema, the description defines the returned row columns, which is critical. Combined with the read-only annotation and the fully described schema, an agent has enough information to invoke this tool correctly.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description restates some of that information (filtering by name or entry hex, sorting by size for largest) but does not add significant semantics beyond the structured parameter definitions.

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 gives a specific verb and resource ('List discovered functions') and even specifies the exact row shape returned (`entry size blocks instrs callers callees src name`). It also scopes the tool against a sibling by saying it is not for imports and should use `symbols` for those.

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

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

It clearly indicates when not to use the tool ('Not for imports') and names the alternative (`symbols`). It also explains the main usage patterns (filtering by name or entry hex, sorting by size for largest), though it does not compare against other function-related siblings like `function` or `function_summary`.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuinely new behavior by disclosing the return shape ('site string_va text' rows) and a hard result cap of 100. It does not say how the cap is enforced (truncation vs. error) or what ordering applies, which keeps it below a 5.

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

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

Two sentences, no filler, with the positive capability and output shape front-loaded and the exclusion second. Every clause carries information an agent needs to select and call it.

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 one-parameter read tool with no output schema, the description supplies the output format and the result bound, which is the main missing structured information. The only gap is unspecified ordering/truncation behavior at the 100-row boundary, which is minor for this tool's complexity.

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

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

There is one parameter with 100% schema description coverage, so the schema already explains 'Entry, any address inside it, or a name'; the description adds no syntax or format detail beyond that. Baseline 3 is correct where the schema does all the parameter work.

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

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

States a specific verb and resource ('List the string literals one function references'), gives the exact row shape 'site string_va text', and caps the result at 100. It also explicitly names the sibling it is not, so the agent can distinguish it from find_function_by_string without opening either 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?

The second sentence gives an explicit negative case ('Not for finding a text's functions') paired with the exact alternative to use ('use find_function_by_string'). That is a clean when-not plus redirect, leaving nothing for the agent to infer.

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

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

Annotations already cover safety (readOnlyHint=true, openWorldHint=false), and the description adds genuine context beyond them: this is a single consolidated call covering many facets, and the response embeds '`# next:` lines' suggesting follow-ups. It stops short of describing failure behavior for a bad address or the format/size of the returned triage output.

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

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

Two compact sentences, front-loaded with the action and payload, followed by the routing rules. No filler, and the alternative is placed after the primary claim where it is most useful.

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

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

With no output schema, the description must convey what comes back and does so by naming each returned facet plus the embedded '`# next:`' guidance. Purpose, routing, and payload are all covered for a single required-parameter read-only 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% and the one parameter is documented as 'Entry, any address inside it, or a name.' The description adds nothing about the address argument beyond 'one function', so the schema carries the semantics alone — the baseline 3 case.

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

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

States a specific verb and scope ('Triage one function in one call') and enumerates the returned facets: shape, loops, jump tables, callers, callees, strings, data. It also distinguishes itself from the sibling `function` ('for the raw block table use function'), so an agent can pick between them without opening either 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?

'Use it before decompile' gives explicit workflow placement, and 'for the raw block table use function' names the alternative and the condition that selects it. It does not address overlap with other siblings that also surface callers, callees, or strings (xrefs, callgraph, function_strings), leaving some selection ambiguity.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: the row layout of the output and the fact that ranges extending past mapped bytes still return something rather than failing. The wording of that out-of-range behavior ('shows what is there') is slightly vague about whether it pads, errors, or truncates, which keeps it from a 5.

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

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

Two tight sentences, front-loaded with the core behavior and output format, followed by routing exclusions. Nothing redundant with schema or annotations is repeated.

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

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

For a two-parameter read-only tool with full schema coverage and no output schema, the description covers purpose, output shape, and alternatives adequately. The only soft spot is the imprecise description of what happens when the range exceeds mapped memory.

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 address forms (0x-hex, decimal, name, `off:<n>`) and the length default/max of 4096 are already fully documented. The description only restates the address framing and adds no syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (hexdump) and resource (raw bytes at an address) plus the exact output shape (`address hex |ascii|` rows). It also rules out three sibling tools by name, so an agent can distinguish it from read, strings, and live_read without inspecting 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?

Explicit negative routing: not for typed values (use read), not for text (use strings), not for a live process (live_read). Each exclusion names the correct alternative, giving a clear decision rule for when to pick 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?

Goes well beyond the annotations: annotations only say destructive/not-readOnly/idempotent, while the description states exactly what is lost (session names) and what happens on failure ('a refused load changes nothing'). That failure-atomicity detail is precisely the kind of behavior an agent cannot infer from hints.

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

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

Three short sentences, zero filler. The destructive side effect and the save_project prerequisite are front-loaded right after the identification clause, ordering the risk before the agent commits.

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 7-parameter destructive load with no output schema, the description covers identification, downstream effect ('the program all tools read'), return shape ('returning its summary'), data loss, and failure semantics. An agent has everything needed to invoke it 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 coverage is 100%, so every parameter including pdb, base, entry, regions, and entry_file_offset is already documented inline. The description only echoes the arch usage, adding no format or default details beyond the schema, so baseline 3 applies.

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

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

States a specific verb (load) and resource (PE/ELF/Mach-O file or raw bytes with arch), plus the crucial scope fact that it becomes 'the program all tools read'. This distinguishes it from load_project, reload, and fetch_pdb without needing 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?

Explicitly tells the agent to call save_project first because session names are cleared, and signals the arch path for raw bytes. It doesn't cover when to prefer load_project or reload, so it stops short of full alternative routing, but the prerequisite guidance is concrete.

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

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

Beyond the destructive and idempotent annotations, the description adds important context: it replaces session names, comments and types, refuses projects matching another binary by SHA-256, and allows bypass only with force=true. That is substantive behavioral disclosure rather than repetition.

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 tightly written sentences with no wasted text. The main destructive action is front-loaded, followed by the refusal rule and the rebuild alternative.

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 destructive, idempotent project-loading tool with no output schema and fully documented parameters, the description covers the key effects, refusal behavior, force override, and rebuild alternative. An agent has enough context 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 coverage is already 100%, so the baseline is 3. The description still adds meaning by explaining that force is specifically for loading a project saved for another binary, including the SHA-256 refusal condition, which goes beyond the schema's shorter wording.

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: it replaces the session's names, comments and types with a saved .json project. This clearly distinguishes it from save_project and gives an agent enough to know exactly what the tool does.

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 describes the refusal condition for projects from another binary and the force=true override, and it names an alternative route for rebuilds via borer://carry. This gives clear when/when-not guidance and 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the bar is lower. The description adds useful behavioral detail beyond that: it returns the same result as resources/read (idempotent read), enumerates discoverable resource categories, and explains '!offset=N!limit=N' pagination, which is non-obvious and not in the schema. It does not cover error behavior for invalid URIs.

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

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

Two dense sentences, front-loaded with verb and resource, and the pagination syntax is appended rather than buried. Slight cost: the 'for hosts without MCP resources' clause is jargon-heavy and could be clearer.

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, and the description defers return-shape knowledge to 'same answer as resources/read' — a reference an agent may not be able to resolve, rather than a description of what a triage/taint/grep response looks like. URI discovery and paging are covered, so it is adequate but leaves the agent guessing about response structure.

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

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

With one parameter at 100% schema coverage, the baseline is 3; the description earns an extra point by explaining that the URI names a borer:// resource, that borer://help enumerates valid ones, and that offset/limit paging is embedded in the URI string — information the schema's one-line 'A borer:// resource URI.' does not convey.

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 gives a specific verb (Read) and resource class (borer:// resource) with concrete examples (triage, taint, emulate, solve, grep), and distinguishes itself from sibling analyses tools by saying it is for 'analyses no tool has'. It also names an equivalence ('same answer as resources/read'), though the odd 'for hosts without MCP resources' phrasing is cryptic without outside context.

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

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

It explicitly states when to reach for it: cases 'no tool has' plus the discovery path 'borer://help lists them', and gives the paging syntax. It stops short of naming a specific sibling to avoid, but the 'no tool has' condition effectively carves out its niche against decompile/disassemble/search.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: it returns the shortest path, and it explicitly reports when no path exists within the depth limit — a notable outcome an agent must handle. It does not describe the return shape, but without an output schema that is a modest 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?

Two tight sentences, front-loaded with the core action and immediately followed by the disambiguation clause. Every clause carries information; nothing is redundant.

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 read-only graph query with full schema coverage and no output schema, the description covers purpose, scope, failure signaling, and alternatives. The only shortfall is the absence of any hint about the result's shape (e.g., the chain as an ordered list of symbols), which an agent might want when interpreting output.

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 all three parameters are documented in-schema, including depth default 24 and max 64. The description's phrase 'within depth' reinforces the depth parameter's role as a search bound, but adds no syntax or format detail beyond the schema. 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?

States a specific verb (find shortest call chain) with the exact resource endpoints (function to function or import) and its depth bound. It also names the two sibling tools it is not, so an agent can distinguish it from callgraph and xrefs purely from the text.

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 exclusions with the alternatives named: 'Not for the whole neighbourhood (use callgraph) or direct callers (use xrefs)'. That is a textbook when-not plus alternative mapping, leaving no ambiguity about tool selection.

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

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

Annotations already cover safety (readOnlyHint=true, openWorldHint=false), but the description adds real behavioral detail the annotations cannot: the row-oriented return format, pointer naming, and the important truncation trait 'stops at the first unmapped byte,' which tells the agent reads can be partial. It stops short of describing error behavior for a fully unmapped address, so not a full 5.

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

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

Two tightly packed sentences with no filler. The primary behavior and output format are front-loaded, and the exclusions are compressed into a single trailing clause.

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 full schema coverage, annotations, and no output schema, the description supplies exactly what structured data cannot: the return shape and the truncation-at-unmapped-byte behavior. Address syntax and count limits are adequately handled by the schema, so nothing an agent needs is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by making the mutual-exclusivity of `kind` and `type` explicit ('or a user type (type)') and by tying each parameter to its mode. It does not elaborate on address forms or the 256-value cap, which remain schema-only.

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

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

States a specific verb (read) plus two explicit decoding modes (kind-based typed values vs. user type) and the output shape (`va value` rows, one row per field, pointers named). It also names what the tool is not (hexdump for raw bytes, live_read for a live process), which lets an agent separate it from siblings 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?

Provides explicit when-not guidance with named alternatives: 'Not for raw bytes (use hexdump) or a live process (live_read).' The two positive modes described in the first sentence imply the when-to-use case, so an agent has both the selection rule and the routing rule.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive semantics. The description adds important context beyond that: the session, loaded file, and annotations survive, while live attaches terminate. It does not cover authentication or failure modes, but the core behavioral effect is disclosed.

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

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

One compact sentence with the primary action front-loaded, followed by preserved-state details and the attach consequence. Every 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?

For a zero-argument restart tool with annotations covering safety flags and no output schema, the description supplies all necessary operational context: what is preserved, what ends, and when to prefer this over a client restart.

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?

Zero parameters means the schema imposes no parameter burden, and no parameter-specific description is needed. The description does not need to explain inputs, and the empty schema is fully sufficient.

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

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

States a specific verb and resource ('Restart the borer server on its rebuilt binary') and immediately clarifies scope by naming preserved state: session, loaded file, annotations. It is distinguishable from client restart and from load_binary/load_project siblings.

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

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

Explicitly says when to use it ('after rebuilding borer') and names the alternative ('instead of restarting the client'). The note 'live attaches end' adds an operational consequence, but there is no explicit 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 annotations already declaring destructiveHint=true and idempotentHint=true, the description adds useful behavior: the file is keyed by SHA-256, lives under the output root, and existing files are preserved unless overwrite=true. It could have been more explicit about what overwrite=true replaces, but the safety-relevant behavior is mostly disclosed.

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

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

The description is two compact sentences with no wasted text. The primary save behavior is front-loaded, followed immediately by restore and overwrite semantics.

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

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

For a two-parameter mutation tool with full schema coverage and annotations, the description covers contents saved, path scope, keying, restore alternative, and overwrite behavior. It does not describe the return value or confirmation behavior, which is a minor remaining gap 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 description coverage is 100%, so both parameters are already documented in the input schema. The description adds context around output-root placement and overwrite behavior, but it does not significantly deepen parameter semantics beyond the schema 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 states a specific verb and resource: saving the session's names, comments, and types into a .json project file. It also distinguishes the opposite operation by naming load_project for restore.

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 points to load_project as the restore alternative and explains the overwrite condition for existing files. It does not explicitly cover when not to use the tool, but the operational context is clear.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false but say nothing about atomicity; the description adds the important guarantee 'a failed script applies nothing' and that name changes require dry_run=false (default true). It still doesn't say whether query/rows can mutate, or what the script returns.

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

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

Three short sentences, front-loaded with the action and the API surface, then the selection rule, then the safety semantics. No filler; every clause carries information the agent needs before writing a script.

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

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

For a two-parameter, potentially mutating escape hatch with no output schema, the description covers purpose, selection, and mutation semantics. It leaves a gap around what the script returns and what URI forms are valid, which matters for a tool whose whole job is arbitrary composition.

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 meaning the schema cannot: it tells the agent what to actually write inside 'code' (query(uri) and rows(uri)) and reiterates the dry_run gating in context. The dry_run explanation partly duplicates the schema text, keeping it from a 5.

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

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

States a specific verb and resource ('Run a sandboxed Rhai script on a snapshot of the program') and goes further by naming the in-script API surface (query(uri), rows(uri)). This is clearly distinguishable from every sibling, which are all fixed-purpose analysis tools, not a general scripting escape hatch.

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?

'Use it when no single tool answers' sets an explicit selection condition that implicitly excludes cases where a dedicated sibling (query, read, xrefs, etc.) already covers the need. It's a strong fallback rule, though it stops short of naming which siblings to prefer for which tasks.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context beyond that: it scans the entire file (implying cost on large binaries), paginates, and formats each hit as a `function: va ...` row. Missing only rate/limit behavior or how results are ordered.

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

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

A single dense sentence front-loads the verb and scope, then mode, then output format, then the exclusion. No filler and nothing an agent needs is buried.

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?

Five parameters are fully covered by the schema, and although there is no output schema the description explains the row format and paging, which fills that gap. The sibling exclusion completes the picture for correct selection.

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

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

Schema description coverage is 100%, so kind, limit, offset, count_only and query are already fully documented with defaults and enum values. The description only restates the wildcard syntax and kind=text mode already in the schema, so baseline 3 applies.

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

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

Names a specific operation (byte search) with its two modes (hex with ?? wildcards, text via kind=text), states the scope ('every byte of the file') and the output shape ('function: va ...' rows, paged). An agent can distinguish it immediately from strings, hexdump, or query without opening the schema.

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

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

Provides an explicit exclusion plus the alternative: 'Not for listing strings (use strings).' That is a clear when-not with a named sibling. It stops short of stating positively when this tool is preferred over hexdump/find_crypto_constants, so not a full 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?

Annotations already declare the tool non-read-only, idempotent and non-destructive, so the description focuses on what annotations can't convey: writes land in the session overlay rather than the binary, and persistence requires save_project. The '? = open question' convention is a genuinely useful behavioral detail. It stops short of explaining overwrite behavior or failure modes.

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

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

Three tight clauses, front-loading the resource and the non-persistence constraint before routing and workflow details. The telegraphic phrasing ('save_project keeps it') is efficient but slightly clipped, which nudges it below 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?

For a three-parameter mutation tool with full schema coverage and no output schema, the essentials are covered: target, non-persistence, alternative tool, dry-run ritual, and persistence step. Only edge cases (overwriting an existing comment, address validity) are unaddressed.

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 earns more by adding the '?' prefix convention that governs how the comment string is interpreted, and by restating the dry-run toggle as a workflow invariant. That is meaning beyond the schema text.

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?

Names a specific verb and resource (comment an address) and adds crucial scope: it writes to the session overlay, never the binary. It also explicitly distinguishes itself from the sibling set_name for the naming case, so an agent needn't read two schemas to choose.

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 the explicit alternative for the adjacent task ('To name it use set_name') and states the dry-run workflow condition ('Dry run until dry_run=false'). It does not spell out when not to use it (e.g., commenting data vs code, or duplicate comment overwrites), but the routing guidance is clear.

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

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

Annotations already flag it as a non-readonly, non-destructive, idempotent mutation, and the description adds genuinely useful context on top: the change lands in the session overlay and never touches the binary, the bulk path is evaluated first, and a conflicting name is rejected unless force is set. The dry_run default restates the schema, but the overlay/conflict semantics are real added value. No output behavior is described.

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

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

Three short sentences, no filler, with the scope constraint front-loaded. The phrase "checked first" is slightly cryptic about what it is checked against, a minor clarity cost in an otherwise tight definition.

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 5-parameter mutation with full schema coverage and no output schema, the description covers the important behavioral envelope: overlay-only effect, conflict handling, and preview-by-default. The one meaningful gap is that it says nothing about what a call returns or how failures report, which matters slightly more given there is no 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 each parameter is already documented, and the baseline of 3 applies. The description does add a precedence hint ("names=... checked first") that the schema does not express, but it adds little else about individual 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+resource ("Name a function or data global") and immediately bounds the scope with "in the session overlay, never the binary," which is the key distinction an agent needs. It does not explicitly contrast itself with siblings like set_comment or set_type, but the naming action is unambiguous enough to tell apart.

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 supplies the operative conditions for a successful call — a taken name requires force=true, and the operation previews until dry_run=false — so the agent knows the preconditions. However, it never states when to choose this tool over set_comment/set_type or when to prefer the singular name vs the bulk names path beyond a bare "instead".

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

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

The description adds useful behavioral context beyond the annotations: it says inputs are checked first and that the operation remains a dry run until dry_run=false. Combined with annotations declaring idempotent=true and destructiveHint=false, this gives a clear safety profile, though it does not describe failure or 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 compact and front-loaded: the main operations come first, followed by the class_layout alternative and the dry-run rule. Every sentence carries actionable information without 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 complex 8-parameter tool with no output schema, the description explains the major modes, the dry-run behavior, and the class_layout alternative. It is largely complete, though it omits what the tool returns and how validation failures are surfaced.

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 parameter descriptions already explain the formats for fields, values, type, address, and dry_run in detail. The description adds mode-level context, such as applying type at an address versus at a function, but does not add much parameter syntax 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 specific operations: defining structs/enums/typedefs, applying types to addresses, and setting function prototypes. It also explicitly distinguishes this tool from class_layout by saying to use class_layout to infer a class.

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 class_layout as the alternative for class inference and gives the key safe-usage rule to dry run until dry_run=false. It does not clarify when to use set_type versus set_name for variable naming, which is a remaining gap.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, so safety is covered; the description adds real behavioral detail by disclosing the output row layout and that it skips bytes of code (i.e., only non-code data sections are scanned). It omits default/max result sizing, but that lives in 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?

Two sentences, zero filler, with the core behavior and output shape front-loaded and the exclusion placed immediately after. Nothing is padded or restated from structured fields.

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

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

For a read-only, six-parameter listing tool with a fully documented schema, the description supplies the missing behavioral pieces (row format, code-section skipping, paging). No output schema exists, but the row layout is described inline, leaving only sizing defaults to the schema.

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

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

Schema coverage is 100%, so limit, filter, offset, encoding, count_only, and min_length are all documented in the schema. The description reinforces paging and the ASCII/UTF-16 choice but adds no format or semantics beyond that text, so the baseline 3 applies.

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

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

Specific verb (list) plus resource (printable ASCII and UTF-16LE strings) plus the exact output row shape `va len enc text`, and it names the sibling it is not for (find_function_by_string). An agent can distinguish it from symbols, hexdump, or search without opening a schema.

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

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

Explicitly carves out a negative case and routes to the correct alternative: 'Not for the code using one (use find_function_by_string).' It does not cover other plausible overlaps such as search or hexdump, so it is clear context but not a full when/when-not map.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real context by disclosing the output row format, module grouping, and paging behavior. It stops short of stating result ordering, what an empty result means, or how paging interacts with count_only, which keeps it below a 5.

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

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

Two sentences, no filler: the first front-loads what is returned and in what shape, the second handles disambiguation. Every clause carries information an agent needs to select or call the tool.

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

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

There is no output schema, so the description must convey the return shape, and it does so precisely (demangled `kind addr name` rows grouped by module, paged). Combined with the fully documented schema and safe-read annotations, nothing essential 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 every parameter is already documented, including the kind enum and defaults; the description only echoes paging and module grouping. That meets the baseline 3 for a fully documented schema with no added semantics such as filter matching rules or limit/count interplay.

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 gives a specific verb ("List") plus the exact resource set (imports, exports, forwards, locals, data) and the row shape (`kind addr name` rows by module). It also names the two siblings it is not (functions, xrefs), so an agent can separate it from adjacent tools without opening a schema.

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

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

It states explicitly what the tool is not for and routes the agent to the correct alternative in each case: discovered code goes to `functions`, call sites go to `xrefs`. That is a concrete when-not plus named alternatives, not implied guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that results are paged and that each type is paired with its applied address, which is useful return-content context, but says nothing about ordering, error behavior, or rate limits.

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

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

A single tight sentence with the core purpose front-loaded and the two exclusions following immediately. No filler.

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

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

For a read-only listing tool with full schema documentation and no output schema, the description gives enough to call it correctly and understand the shape of results (types plus applied addresses). Minor gap: no indication of default ordering or how 'applied' is formatted.

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 limit, offset, filter, and count_only are fully documented in the schema including defaults and max. The description adds no parameter-level meaning beyond that, so baseline 3 applies.

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

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

States a specific verb (List) and resource (user-defined types) plus the scope of results (where each is applied, paged). The exclusion clauses make it trivially distinguishable from set_type and annotations.

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

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

Explicitly routes the agent: use set_type to define a type, use annotations for names and comments, use this tool to list. Both negative cases and their alternatives are named.

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

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

Annotations already declare readOnly/openWorld=false, so safety is covered; the description adds genuinely new behavior: results are grouped one row per referencing function, output is paged, and address semantics differ for imports (calls through slot) vs. Class+offset (field touches). Paging mechanics and ordering are left to the schema's limit/offset text.

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

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

A single dense sentence pair with the exclusion front-loaded and no filler. The clause "`Class+0x24` who touches that field" is a sentence fragment that reads awkwardly, but it is information-dense rather than padded.

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

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

No output schema exists, and the description compensates by describing the row granularity (per function) and paging. With annotations covering safety and the schema covering all four parameters, the only remaining gap is ordering/truncation behavior across pages, which is minor.

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 earns more by explaining what the `address` parameter means in two non-obvious forms (an import resolves to calls through its slot, a Class+offset resolves to field accesses). It adds interpretation the schema's one-line parameter text does not.

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

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

States a specific verb+resource ("List references to an address or name") and immediately qualifies the output shape ("one row per function, paged"). It also names the sibling it is NOT (reaches), so an agent can distinguish it without opening either schema.

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

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

Explicitly excludes the call-path use case and routes it to `reaches`, which is exactly the disambiguation an agent needs. It does not state positive preconditions (e.g., that a binary/project must be loaded), so it stops just 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.