Storm Diff

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the comparison dimensions returned (signature, similarity, callee delta), which tells the agent this is an analytical read rather than a raw text diff. It stops short of saying what happens when the function is missing from one build or how similarity is computed.

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 12-word sentence with the verb and scope front-loaded and the output list as a compact tail. No filler and nothing to trim.

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

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

An output schema exists, so return structure need not be restated. But with 4 parameters at 0% schema coverage and no annotations explaining inputs, the definition leaves the agent guessing about 'use_map' and the required identifier formats, which is the main remaining gap for a read-only analytical tool.

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

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

Schema description coverage is 0%, so the description carries the full burden. 'one function across two builds' loosely maps 'target', 'from_build', 'to_build' for an attentive reader, but 'use_map' is completely unexplained, and nothing clarifies what form build identifiers or the target take (symbol name, mangled name, address).

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 ('Compare') plus a tightly scoped resource ('one function across two builds') and an enumeration of what is produced (signature, similarity, callee delta). It is clearly distinct from a repository-wide diff, though it never names the obvious sibling storm_patch_diff or storm_resolve to sharpen the boundary.

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

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

There is no statement of when to reach for this tool versus storm_patch_diff, storm_resolve, or storm_show. The invocation context (same-named function present in both builds) is implied by 'across two builds' but never stated as a precondition, and no exclusion or alternative is offered.

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