Manage Data

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

Annotations indicate the tool is not read-only (readOnlyHint false) and not destructive by default, but the description explicitly lists import and export actions, which are non-destructive but involve changes. The description adds context about supported formats and actions (e.g., export to JSON/DOT/Mermaid) that helps set expectations. It does not disclose behaviors like overwrite behavior beyond the 'force' parameter, but annotations already cover none of that, so the description's additional action list adds value.

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 long single sentence that enumerates nine actions with parenthetical details. It front-loads the general purpose but becomes cluttered. It could be structured as a list for clarity. It is not concise given the number of actions covered.

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 complexity of a 13-parameter, multi-action tool, the description is too thin. It does not specify which parameters are required or optional for each action, nor does it provide any action-specific parameter requirements or output formats. With no output schema and zero required parameters, an agent cannot reliably infer which parameters to supply for a given action. The description covers the action names but not the full usage context.

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 all 13 parameters are described in the schema. The description lists actions and mentions some associated parameters (e.g., for import_graph: nodes, edges) but doesn't go beyond the schema's own descriptions. The description helps map which parameters apply to which actions, but this mapping is implicit rather than explicit, so it doesn't fully compensate for the lack of action-specific parameter guidance.

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 lists a clear set of actions (export_graph, import_graph, etc.) across multiple domains (graph, issues, trajectories, metrics), which makes the tool's scope evident. However, it packs many operations into one tool, so it does not differentiate itself from siblings like manage_nodes or manage_specs, which likely handle more focused operations.

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 enumerates actions but gives no guidance on when to choose this tool over siblings. For instance, it doesn't explain that manage_nodes should be used for fine-grained node edits while import_graph is for bulk loading. There are no explicit when-to-use or when-not-to-use conditions.

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