update_key_result

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

No annotations are provided, so the description must carry the full behavioral burden. 'Update' implies mutation but nothing is disclosed about whether changes are reversible, whether there are cascading effects on goals, or what the response looks like. For a mutation tool with zero annotation coverage, this is inadequate.

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?

Single sentence, zero filler, but arguably under-specified rather than concise. The sentence is efficient but lacks the contextual detail needed for a reliable update tool.

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?

Moderate complexity tool with 3 params, no output schema, and no annotations. The description minimally covers what fields can be updated but fails to explain progress semantics, whether updates require specific permissions, or how partial updates behave. Adequate but with clear gaps for an update operation.

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 has 100% coverage of the three parameters, giving a baseline of 3. However, the description adds little beyond the schema: it mentions 'progress or details' which loosely maps to steps_current and note, but doesn't clarify whether steps_current can be a target or incrementally updated, nor what format note should take. The description adds marginal value.

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 'Update a key result's progress or details' clearly states the verb (update) and resource (key result) with a specific scope (progress or details). It distinguishes from create_key_result and delete_key_result siblings, though it doesn't enumerate what 'details' encompasses.

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?

No guidance on when to use this tool versus alternatives. There are related goal/key-result tools (create_goal, update_goal, create_key_result, delete_key_result) but no mention of when updating a key result vs updating a goal is appropriate.

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