update_stanza

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

The description discloses behaviors beyond the schema: a mandatory why-log side effect, a 'where_used' return, and subjection to a review policy. These are valuable operational traits an agent cannot derive from the input schema. There is no annotation coverage, so the description must carry the burden of transparency, and it does a solid job for an update tool.

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?

A single sentence that front-loads the primary action (Update a stanza), then adds the immediate side effects and policy constraint. Every clause earns its place, and it is information-dense without being bloated.

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?

With an output schema present, the where_used return is adequately grounded. However, the review policy is vague: an agent does not know when updates get reviewed, what happens on rejection, or whether some fields (roles/tags) have additional constraints. Given seven parameters, zero schema descriptions, and no annotations, the description leaves meaningful operational gaps.

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 all seven parameters are functionally undocumented by both schema and description. However, the parameter names are self-explanatory: stanza_id, why, tags, roles, title, content, description. The description does not explain the required 'why' semantics beyond 'why-log entry', but it does hint that 'why' matters. This is a modest value-add, not a complete compensation for zero schema coverage.

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 states a specific verb and resource ('Update a stanza') and adds two clear side effects ('append a why-log entry', 'return where_used'). This clearly distinguishes the tool from CREATE/DELETE siblings and even from GET/LIST tools, because the description names the unique return value of where_used.

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 implies when to use it: when you need to modify an existing stanza and record a why-log reason. However, it gives no explicit exclusion like 'use create_stanza for new stanzas' or 'use update_skill for skills.' The review policy hint is present but not expanded into actionable guidance, such as what conditions trigger review or how to handle rejected updates.

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