set_state_schema

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

No annotations are provided, so the description carries the full disclosure burden. It does convey the destructive nature ('replace wholesale') and documents the field contract ({name, type, reducer?, default?}) plus the type/reducer syntax. However, it omits error behavior (e.g., invalid Python type expressions), validation of the schema, and side effects on nodes referencing old fields. The documented field structure adds genuine value, but coverage is incomplete.

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?

Three sentences with the core purpose front-loaded in the first sentence and supporting field details in the following two. No filler or redundant phrasing; each sentence earns its place.

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?

An output schema exists, so return-value documentation is not required. The description covers the input contract for 'fields' but lacks error-condition disclosure and side-effect context (what happens to existing nodes or references after a wholesale schema swap). For a schema-replacement mutation, this is a meaningful gap, though the tool has only two parameters and moderate complexity.

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 description coverage is 0%, so the description must compensate, and it does substantially for 'fields' by defining each sub-field's shape and the exact syntax of 'type' and 'reducer' with examples. However, 'project_dir' receives zero explanation—no hint that it is the project path or how it is used. The main parameter is richly documented, but one of the two required parameters is ignored.

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+scope: 'Replace the graph's state schema wholesale.' This clearly distinguishes it from sibling tools like add_node/add_edge (which mutate graph structure) and init_project (project setup). The 'wholesale' qualifier precisely conveys full replacement, making the purpose unambiguous.

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 states what the tool does but gives no guidance on when to choose it over alternatives, and never names a sibling or an exclusion condition. There is no mention of when incremental updates would be preferable or when this wholesale replacement is appropriate. Usage context is entirely implied by the purpose.

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