MCP Tool Graph

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description need not repeat that. It adds context that required payload fields depend on action and are enforced by the 'graph owner,' plus notes about legacy actions being unavailable. However, it does not elaborate on specific side effects or error behavior beyond the examples.

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?

The description is a compact list of five examples, each on its own line, which is easy to scan. There is some redundancy in repeating 'mcp.tool.graph(action=..., payload=...)' for every line, but the overall length is reasonable and every line provides actionable example syntax.

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?

Given the tool's multi-action nature and lack of output schema, the description covers the five callable actions with examples but leaves some gaps. It does not explain return values in any detail (beyond result phrases like 'Graph listing'), nor does it discuss how to handle errors or which payload fields are required or optional for each action. The examples are helpful but not exhaustive.

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 100%, so baseline is 3, but the description adds value by showing concrete payload examples for each action, mapping parameters to their relevant actions (e.g., create uses name and edge_definitions; add_edge uses graph, collection, from_id, to_id). This compensates for the schema's broad parameter list and helps an agent construct correct payloads.

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 opens with example actions ('create - Created graph. mcp.tool.graph(action=create, ...)'), making it clear this tool performs graph operations. It distinguishes from sibling tools by naming graph-specific actions (create, list, add_vertex_collection, add_edge_definition, add_edge), though it lacks a concise one-sentence purpose statement.

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 implies usage via the listed callable actions and examples, but does not explicitly state when to choose this tool over siblings like mcp.tool.collection or mcp.tool.database. It does provide one alternative hint: 'Use mcp.help get for explicit unavailable pages for legacy async actions,' yet that is about availability, not usage context.

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