check_in

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral detail beyond them: the 20/5 result caps, the meaning of `has_more`, the compact form of notify-class entries, and the non-obvious rule that self-filed accepted handoffs become locks tracked in `self_claims_held` rather than being listed. It stops short of describing per-item fields in full, so a 4 rather than 5.

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 scoping and caps are front-loaded and the follow-up routing comes immediately after, which is good structure. It is dense and leans on domain shorthand ('locks', 'self_claims_held', 'notify-class') that a first-time caller must parse, keeping it from a 5.

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?

There is no output schema, so the description carries the return-value burden and does so: it names the subsections, their caps, the `has_more` sentinel, and `self_claims_held`. Combined with the annotation-covered safety profile and the complete single-parameter schema, an agent has everything needed to call and interpret this tool.

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?

With a single parameter at 100% schema description coverage, the schema already documents the format, character class, and examples for `agent_name`, so the baseline is 3. The description only restates that it is a free-form slug and that it filters handoffs addressed to you, adding little beyond the schema.

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 precise verb+resource framing ('pending-work query' returning 'open action handoffs addressed to you or to nobody in particular') with the exact sectioning and caps. It is clearly distinct from siblings like list_handoffs and get_handoff, naming each where relevant.

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?

It states the triggering situation (checking pending work), routes the agent explicitly when results are truncated ('has_more ... use list_handoffs for the rest'), and spells out the follow-up chain ('Next step is get_handoff for the full body, then accept_handoff'). No ambiguity about when to reach for 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.