add_state_evaluator

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

Annotations already declare readOnlyHint=false and idempotentHint=true, but the description adds concrete substance: it explains the reflection-based lookup by struct name, the tree-level tick behavior, and precisely what idempotency means ('an evaluator of the same struct already present is not appended again'). It also discloses the return shape, going beyond what the annotations cover.

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?

Purpose is front-loaded in the first clause, followed by the scope rationale, the idempotency guarantee, and the return shape. Every sentence earns its place and there is no filler.

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 mutation tool with no output schema and full annotation coverage, the description supplies purpose, scope, idempotency semantics, and the return shape, which is enough to invoke it correctly. It omits error/permission behavior, a minor gap given the low 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 coverage is 100%, so both parameters are already documented in the schema. The description adds marginal meaning by clarifying the evaluator is attached 'by struct name, via reflection' and reiterating the tree scope, but does not add format or resolution details beyond the schema. Baseline 3 is appropriate when the schema carries the parameter documentation.

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?

Starts with a specific verb+resource ('Attach an evaluator node ... to a UStateTree') and immediately distinguishes the tool from state-scoped siblings by noting evaluators live on UStateTreeEditorData::Evaluators, not on a state. An agent can tell this apart from add_state, add_state_task and other add_* siblings without opening any schema.

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 scope explanation ('evaluators are TREE-scoped ... so this command takes no state_name') gives clear context for when this tool is the right choice versus state-level additions. It stops short of naming an explicit alternative or stating a when-not condition, so it is clear context without full routing guidance.

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