Rebuild network from a spec

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

The description goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=true). It discloses the tool uses /api/exec, explains the fail-forward behavior (unknown operators/missing params/wires become warnings), details the destructive clear_existing option, and states what the return value contains. This is substantial behavioral context not encoded in the structured 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 longer than typical but every sentence is information-dense. It front-loads the core purpose, then covers prerequisites, behavior, options, and return values in a logical order. A few phrases could be tightened (e.g., 'the REBUILD half of a git-diffable round-trip' is repeated implicitly), but overall it is well-structured and earns its length.

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 complex tool with no output schema, the description is exceptionally complete. It covers the input spec structure, environmental requirements, fail-forward behavior, flag semantics, and the return value format. It also aligns with the destructiveHint annotation by explaining the destructive clear_existing option. No important usage aspect is left unexplained.

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?

The schema already has 100% coverage, but the description adds meaning by explaining the spec structure in plain language ('nodes (name, operator type, parameters as constants/expressions/binds, inbound wires by name, optional x/y)') and by clarifying the effects of clear_existing and auto_layout (e.g., auto_layout 'overrides any manual x/y'). This goes beyond the schema's property 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?

The description clearly states the tool's function: 'Reconstruct a live network inside a COMP from a serialize_network spec — the REBUILD half of a git-diffable round-trip.' It uses a specific verb ('reconstructs') and names the exact resource (a COMP from a spec). It also distinguishes itself from the sibling tool 'serialize_network' by explicitly calling out the round-trip relationship.

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 clear context: it is the counterpart to serialize_network, implying it should be used when reconstructing a previously serialized network. It also gives explicit constraints (requires TDMCP_RAW_PYTHON=on for expression/bind sources, TDMCP_BRIDGE_ALLOW_EXEC=1) and mentions behavior for constant-only specs. However, it does not explicitly mention when not to use it or name alternative tools for simpler node creation, though the round-trip framing is sufficient guidance.

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