Get methodology graph

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which cover safety. The description adds valuable behavioral detail beyond annotations: output caps (200 nodes/500 edges), highest-quality-first truncation, latency <100ms, and read-only on profiles.json + memories. It doesn't note any side effects or error conditions, but the read-only nature plus caps is solid coverage given annotations.

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

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

Four dense sentences, each earning its place: purpose, output structure, safety, and performance/cap limits. The truncation detail and latency are front-loaded with the purpose. No fluff, no repetition. Highly efficient.

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

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

Despite having an output schema, the description thoroughly explains the return shape ({nodes, edges, meta}, with optional truncation fields), the caps, and the visualization use case. With annotations covering safety and idempotency, and the description covering purpose, alternatives, caps, latency, and read-only scope, there is nothing significant left unexplained.

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 only 1 parameter (domain, optional, nullable) with 0% schema description coverage. The description mentions 'domains' as node types but does not explicitly explain what the 'domain' parameter filters or how null vs a value changes behavior. Since the parameter is optional and there's only one, the baseline expectation is that the description explains its effect—it doesn't, though the tool works without it.

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

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

The description clearly states the tool builds a methodology map as JSON graph data for force-directed visualization, listing node and edge types specifically. It explicitly distinguishes from three sibling tools with specific differentiators, making the purpose unambiguous.

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

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

The description explicitly names three alternatives (open_visualization, list_domains, get_causal_chain) and explains what each does differently, giving the agent clear when-to-use and when-not-to-use guidance. It also states this feeds a custom client visualizer, establishing the appropriate context.

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