rebuild_all_graphs

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

With no annotations, the description carries the full burden and delivers. It discloses idempotence ('drops + rebuilds, so rebuilding a healthy source is harmless'), async queue behavior ('kicks them off and returns'), and the unreliable graph_indexed flag ('jobs marked themselves indexed while writing nothing'). It also specifies the return shape ('one entry per source with its job_id (or error)'), which is critical for a bulk async operation.

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 long (7 sentences) but each sentence earns its place: purpose, mechanics, trigger condition, idempotence, default with flag warning, return shape, and async follow-up. It could be trimmed slightly (e.g., 'POST /index-graph' is an implementation detail), but the density of relevant information remains high and the key caveats are front-loaded.

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 tool with 1 optional parameter, no output schema, and no annotations, this description covers the decision to call it, the dangerous flag, the async nature, the return format, and the tracking mechanism. An agent can invoke it correctly and interpret results without needing additional documentation.

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 0%, so the description must compensate for the single boolean parameter. It does exactly that: 'only_missing=true (which filters to graph_indexed=false) will skip the very sources that need repair.' This adds critical semantic meaning beyond the Boolean type and default, explaining why the default is false and why setting it true is dangerous in the intended use case.

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 a specific verb+resource: 'Bulk-build the Neo4j code graph for indexed sources.' It then clarifies the mechanism ('Lists sources, then enqueues a graph job for each') and ties it to a concrete failure mode ('find_definition/graph tools are globally empty'), which distinguishes it from single-source siblings like index_graph. The only_missing caveat further disambiguates correct vs. incorrect usage.

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 states the trigger condition: 'Use this once to repair a bulk import where chunks were indexed but the graph was never built.' It also warns against the harmful alternative ('only_missing=true ... will skip the very sources that need repair') and provides a follow-up action ('poll list_index_jobs(status='running') to track'), giving an agent a complete plan. No alternative tool is named, but the condition is precise enough.

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