commitment_surface

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat that. It adds valuable behavioral context: it is silent by default, only speaks under specific conditions, and each surfacing carries only title + time, never the event body. This goes beyond the annotations and helps the agent understand what to expect.

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 concise and well-structured. It front-loads the core purpose, then explains the conditions, then the output format, and finally the parameter. Every sentence adds value without redundancy. It's appropriately sized for the tool's complexity.

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?

The description is complete for a read-only tool with annotations covering safety. It explains the trigger conditions, output content, and the 'now' parameter. However, it doesn't explain the return format beyond 'title + time only', which might be sufficient given no output schema. It also doesn't clarify what 'split-stick halves' means, but that's domain-specific jargon that might be understood in context. Overall, it's fairly complete.

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 the description must compensate. It explains 'now' as an ISO-8601 instant to evaluate against (default: current UTC), which adds meaning. However, it doesn't explain 'app_id' or 'lead_minutes' beyond what the schema shows (app_id is required, lead_minutes has a default of 15). The description mentions lead_minutes in the context of 'starting within lead_minutes' but doesn't elaborate on its format or constraints. Given the low coverage, the description partially compensates but leaves gaps.

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 the tool's purpose: it surfaces commitments that deserve operator attention based on specific conditions (imminent, conflicting, or unacknowledged changes). It uses specific verbs ('surfaces', 'speaks') and a clear resource ('the dew-rule view'). It distinguishes itself from siblings like commitment_list and commitment_acknowledge by focusing on what needs attention rather than listing or acknowledging commitments.

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 explains when the tool is relevant: when split-stick halves disagree, indicating a commitment is imminent, two active commitments conflict, or a change is unacknowledged. It also notes it is silent by default, implying it should be used to check for attention-worthy items. However, it doesn't explicitly contrast with alternatives like commitment_list or commitment_acknowledge, though the context is clear enough.

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