hey_screen_by_id

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

Goes well beyond the annotations (destructiveHint, idempotentHint) by spelling out the downstream effect of each action on future mail flow, the default destination, and the reversibility constraint ('reversible from the Hey UI's contact page, not yet via MCP'). It even discloses the return shape '{success, error?}' in the absence of an output schema.

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?

Front-loads the action and resource, then branches cleanly into Approve/Reject effects, a reversibility note, the return contract, and sibling routing. Every sentence carries information; none is filler.

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?

With no output schema, the description supplies the return contract, both action semantics, the destination default, reversibility limits, and sibling navigation. An agent has everything needed to invoke this destructive, idempotent tool correctly.

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 coverage is 100% and the schema already documents the destination default (imbox) and enum meanings, so the description largely restates what is structured. It adds only light value by tying destination to the approve branch and clarifying it is ignored on reject.

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?

States a specific compound action (approve/reject) on a precise resource (first-time sender in the Screener) keyed by clearance ID. It is immediately distinguishable from hey_list_screener and hey_screen by the ID-vs-email keying, which the description itself calls out.

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?

Explicitly routes the agent: 'Use hey_list_screener to get clearance IDs' and 'for senders that have already left the screener, use hey_screen by email instead.' Both the prerequisite and the exclusion condition that selects a sibling are named.

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