Storm Write Sites

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, covering the safety profile. The description adds only 'with evidence and confidence,' a mild hint that results carry supporting evidence and confidence scores; it says nothing about format, limits, or how seeds/include_calls influence 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?

A single short sentence with no filler, but for a 9-parameter tool the terseness reads as under-specification rather than efficient front-loading, and its clipped grammar costs clarity.

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

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

The output schema means return values need not be described, but with 9 undocumented parameters and no behavioral or selection guidance, one vague sentence is far too thin for a tool of this complexity. Key toggles like include_calls/include_reads and limit behavior 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 description coverage is 0% across 9 parameters, so the description carries the full burden and largely fails. It loosely signals two addressing modes ('an address or root+offset'), which faintly touches target/root/offset, but leaves build, param, seeds, limit, include_calls, and include_reads completely unexplained.

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

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

The fragment 'Who writes an address or root+offset' conveys the resource (write sites) and the query shape, and pairs with the name storm_write_sites to suggest a write-reference lookup. However the question framing is grammatically awkward and never states plainly 'find code that writes to this location,' so the purpose is inferable rather than stated, and it draws no boundary against siblings like storm_xrefs or storm_find.

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 when-to-use, when-not-to-use, or alternative-tool guidance. With ~20 sibling storm_* tools covering resolution, xrefs, and symbol lookup, an agent gets no signal on why it should pick write-sites over xrefs for a reference question.

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