Faxette

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

Goes well beyond the annotations by disclosing the return payload (document_id, upload_url, upload_headers), the 5-minute PUT window, the 1-hour document_id lifetime, and the reassurance that nothing is faxed or charged. This is the rare case where the non-idempotent, non-destructive profile is made concrete rather than merely hinted at.

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 sentences, each load-bearing: eligibility, call ordering, the upload handshake with deadlines, and the fallback path. The critical ordering constraint and the fallback are front-loaded rather than buried.

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?

Even though an output schema exists, the description still explains the three returned fields because the agent must act on them immediately with a PUT. Nothing about the multi-step workflow, deadlines, or failure path is missing for a five-required-parameter mutation.

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 already 100%, so the baseline is 3, but the description adds real constraints absent from the schema: a 20 MB cap on byte_size and the format allowlist (PDF, JPG, PNG, WEBP, HEIC). It also explains that the returned upload_headers must accompany the exact bytes, tying parameters to the follow-up call.

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 (add a file to a fax) plus accepted formats and size ceiling, and explicitly separates it from the sibling create_fax. An agent can distinguish this from create_fax/send_fax 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 explicit ordering ('Call it once per file, before create_fax, in the order the files should be faxed') and an explicit when-not-to-use branch: if the bytes can't be read, call create_fax without document_ids and let the person upload on the status page. Both the selection condition and the alternative are named.

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 declare a non-read-only, non-destructive, non-idempotent write, and the description adds genuinely new behavior: nothing is sent or charged until the person pays, and the fax waits on the status page for files when document_ids is omitted. Cost/side-effect disclosure of this kind is exactly what annotations can't convey, though "Each call creates a separate fax" largely restates idempotentHint=false.

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 precondition is front-loaded and every sentence carries operational weight — outcome, charge timing, document prerequisite, non-idempotency, next-step routing. It runs long for a three-parameter tool, but no sentence 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?

An output schema exists, so return values needn't be explained, yet the description helpfully names status_url as the person-facing page. Preconditions, charging behavior, and follow-up routing are all covered; the only omission is the create_fax versus send_fax boundary in a sibling set that exposes both.

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 all three parameters, including the signed-in email shortcut and the omit-document_ids fallback. The description reinforces the same points (email only when not signed in, document_ids from create_document) but adds no new semantics such as ordering constraints beyond what the schema states, so the baseline of 3 applies.

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 ("It creates the fax") and immediately describes the output artifact (status_url) and its role in the payment flow. It implicitly separates itself from send_fax via "Nothing is sent or charged until they pay there," but never names that sibling, so the differentiation is inferred rather than stated.

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 a concrete trigger condition ("once the person has confirmed the fax number, and given you their email if they aren't signed in") and explicitly redirects to get_fax_status / get_fax for follow-up. The notable gap is send_fax, a direct sibling that is never mentioned, so the agent must guess when to create versus send.

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=true and idempotentHint=true, so 'It changes nothing' is largely redundant. The genuinely additive disclosure is that calling it while unauthenticated triggers a sign-in flow — a side effect an agent cannot infer from the annotations, and one that explains why a read-only call might produce a prompt.

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, front-loaded with the purpose, then the prerequisite, then the safety note. Every sentence carries distinct information; no filler or restatement of the 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?

An output schema exists, so return values needn't be spelled out, and the one non-obvious behavioral wrinkle (auth requirement and sign-in prompting) is covered explicitly. For a zero-parameter read tool this is complete enough to call correctly on the first try.

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 takes zero parameters, so there is no parameter semantics to document; baseline 4 applies. The description correctly says nothing about inputs and instead spends its words on behavior.

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 ('see which Faxette account the person signed in with') and enumerates the returned fields: name, email, credit, and US/EU copy. This is unambiguously distinct from the fax/document siblings (send_fax, get_faxes, create_document), which all operate on fax artifacts rather than the signed-in account.

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 a clear triggering condition ('Use this to see which Faxette account...') plus a prerequisite: the person must be signed in to Faxette. No explicit exclusions or named alternatives, but the sibling set contains no competing account-inspection tool, so nothing is left ambiguous.

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, yet the description adds two non-obvious operational facts: a polling rate limit while a fax is sending, and the auth behavior that calling it while the user is signed out triggers a sign-in flow. 'It changes nothing' reinforces rather than contradicts the readOnly annotation.

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 purpose, then id provenance, then the two operational constraints. No filler and nothing repeated.

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 the enumeration of returned fields is a bonus rather than a requirement. Auth requirements, rate limiting, id source, and the no-side-effect guarantee cover everything needed to invoke a single-parameter read 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 parameter's own description already says the id comes from get_faxes or create_fax, so the description's id guidance is essentially duplicative. Baseline 3 applies since the schema carries the parameter semantics.

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 and scope ('one fax from the person's Faxette account') and enumerates what comes back: status, price, payment, document file names, history. The singular 'one fax' implicitly separates it from get_faxes, but it never explicitly distinguishes itself from get_fax_status, which a reader could plausibly confuse it with.

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 usage context: call it for a single fax, pass the id obtained from get_faxes or create_fax, and throttle to once a minute while sending. It does not name get_fax_status as an alternative or say when that sibling is preferred, so the routing guidance is incomplete rather than absent.

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: pagination behavior ('Returns 25 at a time, newest first'), the page/next_page contract, authentication behavior ('Needs the person to sign in... asks the app to sign them in'), and safety ('It changes nothing'). This is richer than the readOnly/idempotent hints alone.

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 when to use, then pagination, filtering, alternative tool, auth, and safety. Every sentence is functional with no repetition or 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?

Given the output schema exists and annotations cover safety, the description supplies everything an agent needs: trigger conditions, pagination mechanics, filtering, auth behavior, and the sibling alternative. Nothing essential 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 100% so the baseline is 3, but the description adds practical usage: pass next_page back as page and filter with status using examples like ["failed"] or ["delivered"]. It does not explain the full enum state list, but the schema handles that.

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 ('faxes they've sent from their Faxette account') and scopes it to a person's own sent faxes. It explicitly differentiates from the sibling 'get_fax' by naming it as the tool for a single fax's details.

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 concrete trigger examples ('what they sent last week or which faxes failed') and a clear alternative ('Use get_fax for one fax's details'). Also indicates filtering usage with the status parameter.

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 safety (readOnlyHint, idempotentHint), yet the description adds genuinely new behavioral context: the polling rate limit while sending, and the meaning of checkout_available as the payment gate. 'It changes nothing' is somewhat redundant with readOnlyHint, keeping it out of 5 territory.

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 trigger condition, then the mechanics, then the caveats. Mostly every sentence earns its place, though 'It changes nothing' duplicates the readOnlyHint annotation and could be dropped.

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 one-parameter read tool with an output schema, this covers trigger, data source, returned fields, the checkout_available semantics, and the polling limit — everything needed to call and interpret 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?

Schema description coverage is 100% and the single status_url parameter is already documented in the schema, including an example format. The description only restates that the fax is read from status_url, adding no syntax or format meaning beyond the structured field — the baseline 3 applies.

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 ('reads the fax from its status_url') and enumerates what comes back (status, page count, price, payment, attempts), so it isn't a tautology of the title. It stops short of naming the closest siblings (get_fax, get_faxes) to say how this differs from them, which keeps it at 4 rather than 5.

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 a concrete trigger — 'when the person asks how their fax is doing, or to see whether it's ready to pay' — plus a polling constraint ('at most once a minute while sending'). No explicit exclusion against get_fax/get_faxes, so an agent choosing between the three still has 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?

Annotations flag destructiveHint/openWorldHint, and the description adds the critical facts beyond them: this spends real credit, consent must be explicit, and invoking while unauthenticated triggers a sign-in flow rather than failing. That is exactly the behavioral context annotations cannot convey.

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?

Purpose and funding source are front-loaded, followed by prerequisites and the fallback path in logical order with no filler. It is slightly dense with multi-clause sentences where a two-line structure would read faster, but every sentence carries information.

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 monetary, non-idempotent mutation with an output schema, the description covers consent requirements, prerequisite reads, authentication needs, and the insufficient-credit fallback. Nothing an agent needs before calling 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 100% and both parameters are documented in detail, including the price_changed refusal path for amount_cents. The description reinforces the workflow (confirm price via get_fax before calling) but adds no syntax or value semantics the schema lacks, so baseline 3 applies.

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 ('send a fax') plus the funding source ('from the person's Faxette credit'), which is the exact distinction from siblings like create_fax. An agent can tell this apart from fax creation 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?

Explicit preconditions and sequencing: call get_fax first, confirm credit_price, obtain clear agreement, call only once. It also names the alternative path (status page) when get_account shows insufficient credit, and routes to get_account for the check.

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