mdan_graph_visualize

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

Annotations already declare readOnlyHint: true, which the description is consistent with — no contradiction. The description adds one behavioral fact beyond the annotation: the output is Mermaid markup, which tells an agent the result can be embedded in markdown. It does not mention diagram scope (all nodes vs. filtered), size limits, or rendering needs, but for a no-parameter read operation the annotation plus format is adequate.

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?

Eight words with zero filler, and the most decision-relevant fact (output is Mermaid diagram markup) is front-loaded. Nothing could be cut without losing meaning, and no redundant restatement of the tool name or annotations is present.

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-parameter read-only tool with no output schema, the name plus description cover the essentials: a read-only operation producing a Mermaid representation of the context graph. The minor gap is that 'context graph' is not defined and its relationship to the memory/graph siblings is left implicit, but the tool's low complexity keeps this from being a significant omission.

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?

The tool has zero parameters, so the 100% schema coverage is vacuous and there is nothing for the description to document. Consistent with the baseline for parameter-less tools, the description correctly omits parameter details; no meaning is lost.

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 is a noun phrase ('Mermaid diagram of the context graph') with no verb stating what the tool does — generate, render, or return. It does convey the output format and subject, and the Mermaid format differentiates it from analysis siblings like mdan_graph_impact and mdan_graph_stale, but the action itself is only implied by the tool name, leaving the purpose somewhat vague.

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?

No guidance is given on when to use this tool versus alternatives. With four graph-related siblings (mdan_graph_add_node, mdan_graph_add_edge, mdan_graph_impact, mdan_graph_stale), the description does not state which scenarios call for visualization versus impact analysis or staleness checking, forcing the agent to infer the use case.

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