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

The description goes beyond the annotations by explaining the ambiguous-title behavior: if multiple active objectives match, it refuses and lists them, and objective_id disambiguates. It also discloses the write-tier approval workflow and instructs the agent to act on the first clear ask rather than re-asking. This adds substantial behavioral context beyond the destructiveHint and idempotentHint flags.

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 front-loaded with purpose, then identification behavior, then use case, then approval details. It is efficient and mostly non-redundant, though 'rename or reword' and 'title, description, or year' slightly restate the same idea. The approval block is relevant but contains some command-like jargon.

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 destructive mutation tool with no output schema, the description covers purpose, parameter selection, ambiguity handling, and approval requirements. It does not describe the success return value, but with no output schema and strong schema coverage this is a minor gap rather than a fatal one.

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 the parameter schemas already document each field. The description adds useful selection guidance: objective_title is preferred, and objective_id should be used to disambiguate when multiple goals match. This goes beyond the schema but does not deeply explain all parameter interactions.

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 action (update an existing objective), the exact resource (objective), and the editable fields (title, description, year). It also rephrases the use case as renaming/rewarding or moving to another year, making it easy to distinguish from create_objective and delete_objective.

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 explicitly says 'Use when the operator wants to rename or reword an objective or move it to another year' and frames this as the 'OKR edit door for agents.' It does not explicitly list when not to use it or name alternatives like create_objective, but the intent is clear enough for an agent to route correctly.

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