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

Annotations already declare openWorldHint=true and readOnlyHint=false; the description goes further by disclosing that 'thorough' runs three angled passes at ~3× the credit, that the run consumes workspace inference credit, and that it may return `needs_confirmation`. That is meaningful cost/mutation context beyond the annotations, though no auth or rate-limit detail is given.

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

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

Front-loads purpose, then layers depth behavior, focus guidance, billing, and return signal in dense em-dash clauses. Nothing is filler, though the packing of multiple distinct facts into single sentences makes it slightly harder to skim.

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?

Covers the output shape (cited market context stored on the node), cost model, and a possible confirmation state, which is good for a tool with no output schema. But with 6 parameters, two required and two undocumented, an agent still lacks enough to call it confidently, particularly around the approval flow.

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 only 33%, so the description must compensate. It does add real meaning for `depth` (three passes at 3× credit) and `focus` (steers the run; generic brief otherwise), but `nodeId`, the required `fieldId`, and especially `approvalId` are left completely unexplained — and the link between `approvalId` and the advertised `needs_confirmation` return is never made.

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: 'web-sourced secondary research on a node's idea — market context with citations, stored on the node.' The node anchoring and storage location distinguish it from generic research siblings, though no sibling (e.g. prism_research_run) is named explicitly.

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 clear actionable guidance for parameter choice ('pass focus whenever the user has said what they actually want to know') and explains the depth tradeoff. However, it never says when to pick this node-scoped research over the other prism_research_* siblings — usage is implied rather than routed.

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