Human Handoff relay

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

No annotations are provided, so the description carries the full behavioral burden, and it does disclose the destructive consequences: the link stops working and unread code is wiped. It omits permission/auth requirements and behavior when the request is no longer pending, but the key side effect is explicit.

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?

Two tight sentences, front-loaded with the action and its scope, then the side effects. Nothing is redundant or padded.

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?

For a simple one-parameter mutation with no output schema and no annotations, the description covers what the tool does and its destructive effect. It leaves minor gaps around failure modes (already-cancelled or expired requests) and the return value, which is acceptable here.

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% for the single required parameter request_id, and the description adds no meaning about its format, source, or where to obtain it. With low coverage the description was expected to compensate, and it does not.

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 verb (Cancel) and resource (a pending request) with a scope qualifier (pending). It is clearly distinguishable from read-only siblings like check_request and creation-oriented request_human, though it never names them.

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?

Offers one concrete when-to-use scenario ('your agent got past the step another way'), which implies the normal path already resolved. However, it names no alternative and gives no when-not guidance (e.g., what to do if the request already expired or was consumed).

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

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

With no annotations, the description carries the full behavioral burden, and it delivers genuinely non-obvious detail: 2fa_code values are single-read and wiped after 10 minutes. It is silent, however, on whether polling has side effects for other request types and on rate limits, so the disclosure is strong but not complete.

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?

Two tight sentences with no filler; the state enumeration and the exceptional 2fa_code caveat are both front-loaded and each earns its place.

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?

No output schema exists, so the description must frame the response, and it does so only for the 2fa_code case; it never says what a poll returns for other statuses or how often to poll. Adequate for a simple poll endpoint, but an agent must still guess at cadence and payload shape.

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 single request_id parameter has 0% schema description coverage and the description never mentions it, so it adds no semantic detail about the ID's origin or format (presumably returned by request_human). For a trivial one-string-param tool this is a minor gap, but the description does not compensate for the coverage hole.

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 verb ('Poll') and resource ('a request'), then enumerates the terminal and intermediate states (pending, done, approved, denied, code_ready, expired, cancelled), which makes the tool's role legible at a glance. It doesn't explicitly contrast itself with siblings like cancel_request or request_human, but 'poll' vs 'cancel'/'request' is unambiguous in practice.

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?

Usage is only implied: the status list tells the agent to keep polling until a terminal state, but there is no guidance on polling cadence, whether repeated polls are cheap, or which alternative to use when the caller actually wants to cancel or create a request. No explicit when-not conditions are given.

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

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

No annotations are provided, yet the description discloses the full behavioral profile: Pro tier sends a one-tap link and returns request_id with a later HMAC-signed callback POST, while Free tier is watch-only, logs a would_request, and sends nothing. It also states explicit safety boundaries — never solving CAPTCHAs and never asking for passwords.

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?

Three dense sentences, front-loaded with what the tool does and immediately followed by tier mechanics and limits. Every clause carries information; nothing is padding.

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 still explains what comes back (request_id, later callback POST) and the tier-dependent outcomes. Combined with 100% schema coverage, an agent has everything needed to call this 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%, so baseline is 3, but the description adds meaning beyond the schema by tying notify_webhook/notify_email/callback_url to Pro-tier behavior and Slack/Discord compatibility. It clarifies tier-gated semantics the schema alone does not convey.

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 verb and resource — handing a blocked step to a human — and enumerates the exact cases (CAPTCHA, 2FA/OTP, approval, sign-in). It is immediately distinguishable from siblings like check_request and cancel_request, which handle the lifecycle rather than the initial handoff.

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?

Clearly frames when to use it: for steps the agent 'should not do alone,' with concrete trigger categories. It does not, however, name the sibling to use afterward (check_request) for polling the answer, leaving that routing to inference.

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

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

No annotations, so the description carries the burden. It adds useful context: free tier of 500 calls/day, not metered. However, it doesn't state whether the call itself counts toward quota, rate limits, or whether the upgrade link is static/dynamic.

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?

Two short, front-loaded sentences with no waste. The primary output is stated first, followed by the supporting quota context.

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?

For a no-param, no-output-schema read tool, the description covers what is returned (usage and upgrade link) and the quota context. It lacks detail on return format, but that's minor given the simplicity.

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?

Zero parameters, so baseline is 4. The description correctly indicates the scope is implicit (your key or IP), needing no input.

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 verb ('Show') and resource ('today's usage for your key or IP') plus a secondary output (the upgrade link). It's clearly distinguishable from siblings like budget_status and weekly_report which deal with budgets/reports.

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?

Implied usage via 'today's usage' and the free-tier context, but no explicit when-to-use or when-not-to-use versus siblings like budget_status or weekly_report. The agent must infer that this is a quick self-check rather than a budget query.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses 'Read-only; sends nothing' (no side effects) and the API-key requirement. It stops short of rate limits, failure modes, or delivery format, but the safety profile is genuinely covered.

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?

A single front-loaded sentence with a colon-delimited inventory of report contents; every clause earns its place. It is slightly dense as one run-on, but there is no 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 and no parameters, the description fully compensates by enumerating the report's contents and stating the read-only nature and auth need. An agent has everything required to call it 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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to clarify beyond confirming the tool takes no input, which the empty schema already conveys.

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?

Names a specific verb (summary) and resource (last 7 days), then enumerates exactly what the report covers: stuck points by kind/site, requests sent vs. would-have-been, human answers and latency. This is clearly distinguishable from siblings like check_request and usage_and_upgrade without opening any schema.

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?

Usage is implied (pull a periodic activity summary) and the auth prerequisite 'Needs a free API key' is stated, but there is no explicit when-to-use or when-not wording, nor any pointer to alternatives such as usage_and_upgrade for billing/upgrade needs. Adequate but leaves routing to inference.

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