faxforagents-mcp

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

Annotations declare destructiveness and idempotency, and the description adds the outcome semantics that annotations cannot: success is guaranteed only while queued, degradation to best-effort once sending, and no recall of transmitted pages. It also names the required scope ('fax:cancel'), which is auth context the schema and annotations do not carry.

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 clauses front-loaded with the core action, then the degradation condition, then the hard limit and scope. No filler sentences.

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?

Safety profile is covered by annotations, return shape by the output schema, and the description supplies the timing and scope details an agent needs before a destructive call. The only gap is not pointing to list_faxes/get_fax_status as the source of fax_id.

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 0% and the description never mentions fax_id, its format, or where to obtain it. The single required parameter is self-evident from context ('cancel a fax' needs a fax), so this is adequate but adds nothing beyond the schema's own field name and required flag.

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 ('Cancel a fax') plus the operating condition ('while it is queued'), which is enough to distinguish it from read-oriented siblings like get_fax_status or list_faxes without opening a 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 clear when-it-works guidance ('queued' works, 'sending' is best effort, already-sent pages cannot be recalled), effectively telling the agent when to use it. It stops short of naming an alternative sibling such as request_human_help for cases where cancellation fails.

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?

Rich in most respects: billing ('Metered per page from the wallet'), a security boundary for untrusted fax content, and a scope requirement (document:extract). However, 'Calling again with the same inputs returns the same extraction' asserts effectively idempotent behavior while the annotations declare idempotentHint=false, which will confuse an agent deciding whether retries cost money.

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-loaded with the action, then billing, returns, the untrusted-data warning and scope; nearly every clause carries information. It is a dense single block, so the security constraint competes for attention, but nothing is gratuitous.

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?

An output schema exists and the description still summarizes the return (extraction id, status, text, fields), and it covers billing and trust boundaries. For a metered, state-creating, two-input-mode tool it still omits the one-of input constraint, the meaning of strong_model_if_below, and any failure/page-limit behavior.

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 0% schema description coverage the description must carry the parameters, and it does explain inbox_item_id/document_id as alternative sources and describes the schema parameter's accepted field types well. But strong_model_if_below (number, default 0.75) is never explained, and with zero required parameters it never states that exactly one of inbox_item_id/document_id must be supplied.

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 and resources: OCR-extract schema-defined fields from a received fax (inbox_item_id) or a document (document_id), with citations and confidence. That is far more specific than the tool name alone and clearly distinct from a plain read, but it never names the sibling (e.g. read_inbound_fax) an agent should use when it just wants the text.

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 implies when the tool applies by describing the two source modes and the optional schema ('with a schema ... extract those fields'), but gives no explicit when-to-use versus a plain read, no guidance on when to omit the schema, and no cost/quality tradeoff guidance despite being metered per page.

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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds value by disclosing the required scope 'document:read' and by enumerating the payload (page count, sha256, validation warnings, signed preview URLs), including the non-obvious fact that preview URLs are signed and therefore time-limited.

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: the action and id provenance come first, the payload and scope follow. No filler, no restatement of the name or title.

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 rich annotations, a full output schema, and one required parameter, the description covers everything an agent needs to decide to call it and where the id comes from. Minor gaps (error behavior for unknown/expired ids, whether signed URLs expire) are not covered but are the only remaining omissions.

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 0% and document_id has no description, so the description carries the burden. It does compensate meaningfully by naming the provenance of the id (values returned by prepare_fax), which is the one non-obvious semantic. It does not state the id format or what happens with an unknown id, keeping it short of a 5.

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 ('Fetch a prepared document by id') and immediately anchors it to the sibling that produces the ids ('the ids prepare_fax returns'). This distinguishes it from prepare_fax, list_faxes, and the other siblings without requiring the agent to open a 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?

The clause 'the ids prepare_fax returns' makes the prerequisite workflow explicit: prepare first, then fetch by the returned id. The required scope ('document:read') tells the agent the authorization context needed. It stops short of naming exclusions or failure cases, so it is clear context rather than full when/when-not guidance.

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 already declare readOnlyHint, idempotentHint and destructiveHint=false, so the 'Read-only' sentence is largely redundant. The genuinely additive disclosure is the required 'billing:read' scope, which tells the agent an authorization prerequisite exists. It does not say what happens when that scope is missing (error vs. empty), which keeps it from a 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?

Two short sentences, front-loaded with what the tool returns, followed by the safety and scope facts. Nothing extraneous beyond the mildly redundant 'Read-only'.

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 zero-parameter read with an output schema, the description covers the resource, the unit of measure, the safety profile, and the required scope. An agent has everything needed to decide to call it and interpret the result.

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?

There are zero parameters, so the baseline is 4 by rule. The description does add meaning about the returned value's unit (USD micro-units), which helps interpret output even though it is not a parameter concern.

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 precisely what is returned (available and held wallet balance for this key's environment) and in what unit (USD micro-units). No sibling tool touches wallet balances, so there is no ambiguity to resolve.

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: an agent infers it should call this when it needs funding information before a paid action such as quote_fax or send_approved_fax. There is no explicit 'use when' statement, no mention of whether it must be called before sending, and no alternatives discussed.

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?

While annotations cover the fundamental safety profile (readOnlyHint=true), the description adds critical behavioral context by specifying that it deals only in 'facts about the account' and does not perform validation or evaluation of a send action.

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 highly concise and structured. It delivers the core function, scope, and critical distinction from alternatives in two efficient sentences.

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 the zero-parameter input and comprehensive annotations, the description is complete. It successfully addresses the most likely point of agent confusion: differentiating it from the sibling tool, `quote_fax`.

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 tool accepts zero parameters, meaning the description cannot add semantic meaning to inputs. Since schema coverage is 100%, the baseline of 4 is appropriate for a parameter-free tool.

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 clearly identifies the purpose as providing an 'account-level view' of 'limits, routes, formats, prices and scopes.' It explicitly defines the resource (account capabilities).

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 provides explicit guidance on when NOT to use the tool, stating it 'never evaluates a send.' It contrasts itself directly with the sibling tool 'quote_fax,' providing clear usage boundaries.

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 already cover read-only, idempotent, non-destructive behavior, but the description adds useful context: the evidence is carrier-reported rather than legal proof, where the evidence appears, and the required fax:read scope. It does not describe pagination or response structure, though an output schema exists.

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 three tight sentences that front-load the status enumeration and then explain evidence semantics and scope. It is efficient, though the dense parenthetical about evidence fields borders on detail that could be deferred to the output 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?

For a read-only single-resource status tool with an output schema and safety annotations, the description covers purpose, statuses, evidence meaning, and authorization scope. The only notable gap is the unexplained fax_id parameter.

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 input schema has 0% description coverage and only one required parameter, fax_id. The description mentions 'one fax' but does not explain the fax_id format, where to obtain it, or any constraints, so it fails to compensate for the schema gap.

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 verb and resource: retrieving 'the state of one fax and its attempts,' and enumerates the possible states. This clearly separates it from list_faxes and other sibling tools that act on many faxes or mutate 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?

It gives a clear condition for use: 'Once the fax is delivered or partial this is the one place for the carrier's delivery evidence.' However, it does not explicitly name alternatives or state when not to use this tool.

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 already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — it works without an API key — but says nothing about what is returned when `section` is omitted or what happens with an unrecognized section name.

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 compact sentences with the subject and content scope front-loaded, and the section list placed last where it belongs. Every phrase maps to usable information; nothing is 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?

With a single optional parameter and an output schema present, the description only needs to say what documentation exists and how to address it — both are covered. Return format is handled by the output schema, so its absence from the description is not a gap.

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%, so the description must carry the parameter burden, and it does: it enumerates the valid sections (overview, send, states, errors, approvals, policies, agents, inbox, ocr) that the schema does not encode as an enum. It stops short of noting the parameter is optional/nullable or the default behavior when it is omitted.

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 names a specific resource — 'The manual for Fax for Agents' — and enumerates the topics it covers (send flow, fax states, error codes, approvals, policies, agents, inbox, OCR). It is obviously distinct from every sibling tool, which are operational actions rather than documentation.

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 implies the guide should be consulted for background on the service ('Works without a key' hints it is safe to call early), but it never states when to prefer this over, say, get_fax_capabilities or when a section lookup is warranted. Usage is inferable rather than explicit.

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 already declare readOnlyHint/idempotentHint and no destructive behavior; the description reinforces this with 'Read-only; it never decides' and adds genuinely new context — the required scope approval:read and the fact that this tool only observes, never resolves. It does not mention polling/rate behavior, so not quite a 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?

Three tight sentences, front-loaded with what the tool returns, followed by state enumeration and the downstream handoff. Every clause (states, approval_id, help-request behavior, scope) earns its place with no repetition of schema fields.

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?

An output schema exists, so return values needn't be spelled out, yet the description still enumerates the possible states and explains the approval_id handoff. Combined with the scope disclosure and the read-only/no-decision guarantee, an agent has everything needed to call and act on 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?

One required parameter with 0% schema description coverage, so the description carries the burden — it implies review_request_id is the ID returned by request_human_review, which is meaningful routing context. However it never states the ID format or confirms that it must come from that call, leaving a gap against the 0% coverage baseline.

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+resource — returns the state of a single review request — and immediately anchors it to the originating tool (request_human_review). It also differentiates the two request flavors (approval vs. help) and names the downstream sibling send_approved_fax, so an agent can place it in the workflow 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?

Usage context is clear: call it after request_human_review to learn whether the request is pending/approved/rejected/revoked/expired, and take the returned approval_id to send_approved_fax. It does not state a 'do not use when' condition or clarify polling expectations, so it stops just short of explicit exclusions.

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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so credit goes to what the description adds: result ordering ('newest first'), cursor-based continuation, and the required 'fax:read' scope. That is meaningful behavioral context beyond the structured fields, though rate limits and response shape are not addressed.

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 compact sentence-cluster that front-loads the resource, then ordering, filtering, pagination, and scope. No filler content.

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?

An output schema exists, so return values need not be explained. With ordering, pagination, and auth scope covered, the only real omissions are what 'limit' does and what values 'state' accepts — minor given the low-complexity 3-param surface.

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 0%, so the description has to compensate. It explains 'state' as an optional filter and 'cursor' as the pagination token, but 'limit' (default 20) is never mentioned and the accepted values for 'state' are left undefined, so compensation is only partial.

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+resource ('Sent faxes of your organization') and scopes it to outbound items, which implicitly separates it from the inbound sibling list_inbox. It does not name any sibling explicitly, but the outbound framing is unambiguous.

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 phrasing 'optionally by state' and 'pages continue with cursor' implies how to use the tool, but there is no explicit when-to-use vs. when-not guidance and no mention of siblings like list_inbox or get_fax_status. Usage must be inferred from the description.

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 already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real context beyond them: result ordering (newest first), payload shape (metadata only), and the required auth scope (inbox:read). It does not cover pagination or result-size behavior, keeping it at a 4.

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 compact fragments with zero filler, ordering and payload scope stated first. Every clause carries information the agent needs and nothing is repeated from structured fields.

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?

The output schema exists, so return values needn't be documented, and the scope plus ordering notes cover the essentials of a read. However, for a cursor-paginated listing tool, the absence of any pagination or page-size guidance leaves a real operational gap.

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% and the description says nothing about either parameter. Neither 'limit' (default 20) nor 'cursor' is defined, and the agent gets no guidance on page size or how to resume pagination, which is the one thing a cursor-based listing tool must explain.

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 names a specific resource (received faxes) and front-loads its output shape (metadata only: sender header, pages, status). 'Metadata only' implicitly separates it from read_inbound_fax, which would fetch content, though no sibling is named. Purpose is clear but sibling differentiation is left to inference.

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?

There is no explicit when-to-use statement and no named alternative. The 'metadata only' phrasing hints that a different tool is needed to read fax content, but that routing decision is left entirely to the agent to infer.

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?

Beyond the annotations, it discloses the validation step, the returned fields (id, sha256, page count), that it never sends, and the required scope (document:write). These are concrete behavioral facts an agent needs. It doesn't detail side effects of validation failure or whether drafts persist, keeping it at a 4.

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 core action, followed by return values and scope. No filler; each sentence adds a distinct fact.

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 an output schema and annotations present, the description covers the action, input modes, validation behavior, scope, and the critical 'never sends' distinction. Nothing essential for correct invocation is missing.

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 0%, so the description must compensate. It maps text/markdown/html/upload_id to their input purposes and file-type expectations, but leaves 'filename' unexplained and doesn't state that sources are mutually exclusive (only one of the five should be supplied). Partial compensation warrants a 3.

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 (create a document to fax) and enumerates accepted inputs. The line 'Never sends' cleanly separates it from send_approved_fax and other send-related siblings.

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 'Never sends' clause implicitly signals this is the preparation step preceding send_approved_fax, and 'register a completed REST upload' clarifies the upload path. It stops short of explicitly naming a follow-on sibling or stating when-not-to-use, so it's strong but not fully explicit routing.

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 already cover readOnly/openWorld/idempotent/destructive flags, yet the description still adds real value: it discloses the pricing unit and basis (cover sheet counted as a billable page), the response contents (micro-unit amount, 10-minute expiry, policy verdict, first failing rule, human-approval flag), and the fax:quote scope. The only gap is that it never addresses repeat-call behavior, which matters given idempotentHint=false and a 10-minute expiry — it is unclear whether calling twice mints two distinct quotes.

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-loaded with what the tool returns and what it does not do ('Nothing is sent'), with scope last. Four dense sentences with no filler, though the return-value sentence is heavy for information an output schema already carries.

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 a complex policy-evaluating tool with an output schema, this is nearly complete: it explains the nondeterminism risk implied by expiry, the policy outcome semantics, and that no fax is transmitted. The remaining gap is sequencing guidance relative to prepare_fax and send_approved_fax.

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%, so the description carries the whole burden — and it does. It names the cover sheet fields (to_name, from_name, subject, message) that the schema leaves as an opaque string map, and specifies E.164 formatting for the destination. Only document_id is left implicit.

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: exact price for one document to one E.164 destination. It also distinguishes itself from the send flow by noting the cover sheet is a billable page, which an agent could not infer from the name 'quote_fax' alone.

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 same evaluation the server runs at send time, so no separate dry run. Nothing is sent.' clearly establishes the pre-send/prepare context. It stops short of naming siblings such as prepare_fax or send_approved_fax, so the agent must infer that this belongs before a send, not instead of one.

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 already declare read-only, idempotent, closed-world and non-destructive, so the description adds genuine incremental value: it discloses that text is present only when an extraction exists and states the required inbox:read scope. The explicit prompt-injection warning about the sender header and text being untrusted data is a meaningful behavioral carve-out. It stops short of describing not-found or error behavior.

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 what is returned and followed by the trust-boundary constraint and scope. 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?

An output schema exists, so return shapes need no elaboration, and the description covers contents, conditional text availability, and the untrusted-data rule. The remaining gap is the sole required parameter, whose meaning and provenance are left unstated.

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?

There is one parameter, inbox_id, whose schema description coverage is 0%, and the description never mentions it or its format. The scope line 'inbox:read' hints at inbox context but does not explain the identifier the caller must supply.

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 resource and its contents: a single received fax with metadata, document reference and optional extracted text. The singular scope implicitly distinguishes it from the plural list_faxes sibling, but no sibling is named explicitly.

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: you read one fax, presumably after obtaining its id, and the 'inbox:read' scope hints at the requirement. No alternative or exclusion is named, so an agent must infer that list_faxes/list_inbox precede this call.

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?

Adds substantial context beyond annotations: it discloses that the request mails the organization, that the approval is bound to quote details (sha256, destination, sender, amount, expiry), that the fax message is shown as data, that it grants no permissions, and the required scope 'approval:request'. It does not mention that repeated calls create new requests (idempotentHint=false) or what expiry means operationally, leaving some behavioral gaps.

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-loaded with the two-mode branching ('With quote_id' / 'Without quote_id'), which makes parsing fast. The sentences are dense and clause-heavy, and the trailing 'Scope:' fragment is terse, but nothing is wasted.

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?

An output schema exists, so return values need not be explained, and the description covers both modes, the side effect (mail), the permission scope, and the next step. Minor gaps remain around expiry semantics, duplicate-request behavior, and how the required message is used in the quote branch.

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 0%, so the description must carry the load, and it does for quote_id (binds approval to a quoted send with a specific payload) and fax_id (optional, associates a received fax and renders its message as data). The required 'message' parameter is only implicitly characterized ('whose message is shown as data'), leaving its content expectations underspecified.

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 ('ask a person to approve that quoted send' / 'ask a person for help') and cleanly splits the tool into two modes keyed on quote_id. An agent can tell exactly what this does versus prepare_fax or send_approved_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?

Explicitly states when to use each branch: with quote_id for approving a quoted send, without it when stuck or when a received fax asks for something. It also names the downstream tool ('a human decides, then send_approved_fax'), closing the loop on what to do after the review resolves.

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?

Adds substantial context beyond the annotations: the scope requirement (fax:send), that the response means queued-not-delivered, and the idempotency contract (same idempotency_key returns the same fax). This complements destructiveHint/openWorldHint with the actual auth and retry behavior an agent needs.

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?

Four tight sentences, front-loaded with the action, then the authorization branch, then retry semantics, then the outcome and scope. No sentence merely restates the tool name 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?

For a mutation tool with a rich output schema, the description covers the essentials an agent cannot infer: authorization branching, idempotency, the queued-only result, the polling tool, and the required scope. Nothing critical is missing for correct invocation.

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 0%, so the description must carry the load and largely does: approval_id is explained with its source and binding rule, idempotency_key with its repeat semantics, and quote_id is implied by the conditional send logic. Only client_reference is left unexplained, keeping it short of a 5.

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 ("Queue a quoted fax") and makes the input precondition (a quote produced by quote_fax) explicit, which separates it from prepare_fax and quote_fax. An agent can tell from the first clause what this tool does and what it acts on.

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 branch condition: sends as-is when authorization_required=false, otherwise requires an approval_id from request_human_review or a delegated policy. It also names the follow-up tool (poll get_fax_status), so both the entry condition and the after-call routing are covered.

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