FaxOnline

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely non-obvious behavior: a 'processing' state means not yet delivered, and there is an explicit polling rate limit of one call per 15 seconds. It stops short of describing the full return shape, but the added state semantics and throttling guidance are substantive.

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 short sentences with no filler; the action, the return, and the polling constraint are each front-loaded and earn their place. No redundancy with the title or schema.

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 carries the burden of describing returns and does so at a high level ('payment and delivery status'), plus explains the processing state. It could enumerate the possible status values, but for a single-parameter read tool it is nearly 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 100%, so the draft_token parameter is already documented. The description reinforces that the token is secret and originates from prepare_fax, adding mild value, but offers no format or validation detail beyond the schema. Baseline 3 is appropriate.

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 ('Check your prepared fax') and immediately names the key artifact ('secret draft_token') that ties it to the prepare_fax workflow. An agent can distinguish this read-only status check from its only sibling, prepare_fax, without opening the 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?

Gives an explicit operational constraint — poll no more than once every 15 seconds — which is real usage guidance and prevents hammering. It doesn't frame when-not-to-use it versus prepare_fax, but the prerequisite relationship (token comes from prepare_fax) is clear from the description and schema.

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?

Annotations only cover idempotentHint and destructiveHint; the description adds the real behavior an agent needs: the document is stored (a side effect), nothing is sent or charged yet, and checkout is the authorization step. The 'reuse draft_token with identical inputs for retries' guidance reinforces the idempotency hint rather than contradicting it, though it doesn't state a retry window or what happens on a mismatched-input reuse.

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 tight sentences, front-loaded with the action and its non-effects before the format and secret-handling details. The fax_number formatting sentence is largely duplicated from the schema, which is dead weight but not enough to derail the structure.

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 usefully names the return values (price, checkout link) and covers the payment/authorization model and input format. It omits the natural follow-up relationship with get_fax_status for status polling, which is the one gap for an agent orchestrating the full fax flow.

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 100%, so all five parameters are already documented, including the fax_number format and the 10 MiB base64 limit. The description restates the fax_number rules verbatim and adds only the 'keep draft_token private' caution, so it lands at the baseline rather than adding new semantic detail.

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 ('Prepare one PDF fax') plus the explicit return payload ('price and Stripe checkout link'), and draws a hard boundary against sending/charging. An agent can tell this apart from get_fax_status without opening either 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?

Clearly frames the two-phase flow: this call stores the document but does not send or charge, and checkout is what authorizes sending to the displayed recipient. It also gives the retry condition ('reuse it with identical inputs'). It never names the sibling get_fax_status as the follow-up for checking delivery, so the routing guidance is incomplete.

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