update_intent

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

No annotations were provided, so the description carries full burden for behavioral disclosure. It excellently covers key behaviors: the collision-check dependency on stale globs ('stale globs silently miss real collisions'), the TTL heartbeat mechanism with explicit expiry ('active intents expire after ~48h without one'), the side-effect of returning fresh overlaps when calling with just the id, and the importance of treating 'warn' responses seriously. This is comprehensive for a mutation 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?

The description is compact yet dense with information, using front-loaded key points (verb, resource, when-to-use) then expanding logically. Every sentence adds substantive value: purpose, use-cases, side-effect, warning, and explicit exclusion. No redundancy or filler. It efficiently uses punctuation (semicolons, dashes, parentheses) to pack information without verbosity.

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?

Given the complexity of this tool (5 parameters, mutation, TTL-aware, collision-sensitive) and the absence of an output schema, the description is remarkably complete. It covers all critical aspects: usage triggers, parameter semantics, side-effects (overlaps, warn), failure modes (stale globs), lifecycle (TTL expiry), and what not to do (complete_intent). The description fully compensates for missing annotations and output schema.

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 100%, so the baseline is 3. However, the description adds significant meaning beyond the schema: it explains the impact of stale globs on collision detection ('collision checks run against these fields'), clarifies that calling with just the id 'returns fresh overlaps' (a behavioral side-effect not in any parameter description), and gives real-world time context ('~48h'). This elevates the score well above baseline.

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 clearly states 'Update an in-progress intent' as the primary purpose, with specific verbs (update, revise, renew) and resources (summary, touches, TTL). It distinguishes itself from 'complete_intent' by explicitly stating 'Never use this to finish work — call complete_intent for that.' This matches the sibling list and provides clear differentiation.

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 provides explicit guidance on when to use the tool: 'Call when the work changes shape' (revise summary or touches) or 'when work runs long' (renew TTL heartbeat). It also states what NOT to do ('Never use this to finish work') and points to a sibling alternative ('call complete_intent for that'). Additionally, it warns about treating a 'warn' response similarly to post-time checks, giving clear behavioral context.

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