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

Annotations already flag destructive behavior, but the description adds substantial context: schema and code are reverted but Neo4j data is not, the graph API is redeployed with the old schema, concurrent operations are refused, and RationalBloks updates cause temporary refusals. This exceeds annotation coverage meaningfully.

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?

Though long, every sentence earns its place: the warning is front-loaded, the non-rollback exception is explicit, and concurrency/retry behavior is described precisely. No filler or repetition beyond what is operationally necessary.

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 destructive, non-idempotent operation with no output schema, the description covers prerequisites, side effects, exclusions, concurrency behavior, and retry guidance. An agent has enough information to invoke it correctly and recover from rejection conditions.

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 the baseline is 3. The description adds practical value by telling the agent to resolve the version parameter via get_graph_version_history and by framing version as a commit SHA, which enriches the schema's bare descriptions.

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?

Description uses a specific verb and resource: 'Rollback a graph project to a previous version.' It goes beyond a restatement by clarifying exactly what is reverted (schema AND code) and what is not (Neo4j data), which distinguishes it from generic rollback_project and other graph 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?

Clear usage context is provided: use get_graph_version_history to find the commit SHA, wait with get_job_status if another operation is running, and retry during RationalBloks updates. It does not explicitly contrast with the rollback_project sibling, so it stops short of full when/when-not alternatives guidance.

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