Claim Decision Task

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

Even though annotations already mark this as not read-only and not destructive, the description adds significant behavioral context: claiming is the payload fetch, leases can expire and be reclaimed, a conflicting live claim returns HTTP 409, and auth failures return 403 with specific error codes (decide_grant_required, insufficient_scope, insufficient_tier) and instruct the agent not to retry. This goes well beyond what annotations alone convey.

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 long but tightly structured with clear labels: the core behavior, USE WHEN, NOT FOR, and AUTH. Every sentence carries operational value—there is no filler or repetition. The most critical facts (claiming fetches the bundle, save the lease fields, use first_cursor) are front-loaded.

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 that there is no output schema, the description compensates by explicitly naming the decision bundle fields, the package descriptor fields, the meaning of null first_cursor, the follow-up tool to use, conflict behavior, and authentication requirements. This is complete enough for an agent to invoke the tool correctly without further inference.

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 covers 100% of the parameter information: task_id is described as 'Decision task UUID' with format and pattern constraints. The description adds workflow context but does not add new parameter-level semantics beyond the schema. With full schema coverage, the baseline of 3 is appropriate; there is no gap to compensate for.

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 ('Claim an available decision task'), the target resource, and a concrete outcome ('receive the decision bundle') with a detailed list of returned fields. It explicitly distinguishes itself from siblings by noting that claiming is the payload fetch and there is no separate get. An agent can clearly tell this apart from talonic_read_decision_package, talonic_heartbeat_decision_task, and talonic_submit_decision_task.

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 USE WHEN guidance ('ready to decide a listed task') and a NOT FOR section naming the exact alternatives: talonic_heartbeat_decision_task and talonic_submit_decision_task. It also provides workflow direction: save execution_epoch and lease_expires_at, then read with talonic_read_decision_package starting at first_cursor. This leaves no ambiguity about when to invoke this tool versus its siblings.

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