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

With readOnlyHint false and destructiveHint false, the description carries full responsibility for behavioral disclosure, and it does so exhaustively. It reveals that the graph is executed for real, that endpoint wiring performs live MCP calls, that doc_input triggers a real registry lookup, that private/missing actors cause a typed agent_unavailable error, and that model_policy 'required' can refuse execution with model_unavailable. It also notes non-Haiku models need the owner's API key. No contradictions with annotations.

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 and dense, but every sentence earns its place given the tool's complexity. It front-loads the core purpose, then systematically unpacks each parameter with backtick-delimited field names. Structure is logical (purpose → structure_type → nodes → edges → lifecycle). It could be slightly tightened, but the density is justified for a tool this intricate.

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 6 parameters, 1 enum, no output schema, and rich behavioral nuances, the description is remarkably complete. It covers all parameters, explains error types, clarifies execution semantics, and states the post-condition (saved Working Rig, runnable via run endpoint). An agent could call this tool correctly without additional 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%, providing baseline 3, but the description vastly exceeds that baseline. It explains the semantic meaning of fields beyond their schema descriptions: 'agent' as a sub-agent persona actor, 'endpoint' + 'tool' + 'params' wiring to a live MCP server, 'doc_input' as a light listing step, 'model_policy' behavior, and edges constraints. This transforms the schema from raw data into actionable knowledge.

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 clear, specific statement of what the tool does: 'Build + save a multi-node Rig as a GRAPH the runtime executes for real'. It distinguishes itself from sibling rig tools (rig_node_add, rig_run, etc.) by emphasizing it authors the whole graph, not a single node, and calls it 'the agent-side mirror of the human Rig Builder canvas'. This leaves no ambiguity about its function.

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 provides strong contextual guidance: it explains the two structure types ('dag' vs 'stateful_graph'), the conditions for each, and how the graph becomes a saved Working Rig runnable via the run endpoint. It does not explicitly name alternative tools (e.g., rig_node_add for single-node edits) or say 'use this instead of X', but the framing as a complete graph authoring tool clearly implies its niche. A small deduction for not stating explicit 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.