Reciba

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds 'Stores nothing', which usefully reinforces the no-side-effect nature, and it states the accepted numeric range. It does not need to repeat annotation-covered traits, so this is a solid addition.

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 two short sentences with zero waste. The core purpose and example are front-loaded, and 'Stores nothing' is a compact, useful behavioral note.

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 formatting tool with full annotations and an output schema, the description covers purpose, range, example, and side-effect profile. Minor gaps like behavior for out-of-range input are not critical because the range is stated and the tool is read-only.

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 parameter itself is well documented. The description goes beyond the schema by supplying the accepted range (0 to 999.999.999,99) and a full input-to-output example, which clarifies accepted formats and expected output shape.

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 (writes) and resource (amount in Brazilian reais in words), with a concrete example and format. It does not explicitly differentiate from siblings, but the sibling tools are document-related and the purpose here is unmistakably a formatting utility, so the risk of confusion is low.

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 by the description: convert a monetary amount to its written form. There is no explicit when-to-use guidance, no mention of alternatives, and no exclusions. For a simple utility this is adequate, but it lacks the routing cues that would earn a higher score.

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 (readOnlyHint, idempotentHint, openWorldHint=false, destructiveHint=false), so the description is not carrying that burden. It still adds meaningful context beyond the annotations: "Reads nothing about the person" is a privacy guarantee an agent would not otherwise know, and the enumerated coverage gaps (what is not available here and where those documents must be obtained instead) prevent misdirected calls.

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 positive capability statement is front-loaded in the first sentence, with the exclusions following as supporting detail. The negative enumeration is long (six document types across two sentences), but each item heads off a plausible wrong expectation, so the length is largely earned rather than 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 need no explanation here, and the description covers scope, the identity of the id field's consumer, and the boundary of what is unavailable. What remains unstated is the intended call sequence with prepare_document, which is implied but never spelled out.

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 the baseline is 4 and there is nothing further for the description to disambiguate. It correctly avoids inventing parameter guidance that does not apply.

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 verb and resource ("Lists the document types Reciba can draft from a conversation") and states the concrete return content: the supported document types and the fields of each one. It also distinguishes itself from the sibling prepare_document by explaining that the returned type id is exactly what prepare_document takes.

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 clear context for when this tool is the right one (discovering available document types and their ids before drafting) and explicit exclusions — nota fiscal, health-service receipts for income tax, declaração de residência, declaração de união estável, declaração de renda, and recibo de salário are all out of scope. It stops short of a direct instruction like "call this before prepare_document," leaving that step to be inferred from the type-id reference.

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 materially beyond the annotations: it discloses that the call only creates a preview plus a single-use link, that it "issues, charges and sends nothing," and that identifiers (CPF/CNPJ/RG) are refused and must be added on the site. That reconciles cleanly with destructiveHint=false and readOnlyHint=false and clarifies why each call is a fresh draft (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 core action and its limits are front-loaded in the first two sentences, and the long exclusion clause is necessary routing information rather than filler. The final formatting sentence is dense and partially duplicates the schema, which keeps it from a 5.

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 non-destructive draft-creation tool with an output schema and full parameter documentation, everything an agent needs is present: what is produced, what is not done, what input formats are accepted, and which adjacent use cases belong elsewhere. No material gap remains.

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 tipo and the open-ended campos object are already documented, including the value formats. The description still adds real semantics: which type identifiers exist, that campos is keyed by the type's field ids from list_document_types, and the hard constraint that CPF/CNPJ/RG values are rejected.

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?

Opens with a specific verb and resource set ("Drafts a Brazilian payment receipt, rent receipt, service quote or service order on Reciba") and states the output ("returns a single-use link"). The enumerated document types map directly onto the tipo values, so an agent can tell exactly what this tool produces versus the listing/verification 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?

Gives explicit when-to-use ("documents the person issues about their own service, sale or rental") and explicit when-not (nota fiscal, receipts a third party must issue such as a dentist or landlord, Receita Saúde receipts, pricing advice). It also states the division of labor: the tool prepares, the person reviews and issues from their own account.

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 readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds real context beyond them: the explicit privacy guarantee (no names or e-mail addresses returned) and the fact that results include reporting destinations for forged documents. It does not describe behavior for invalid or malformed codes, 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?

The core action and accepted inputs are front-loaded, and the privacy and reporting details follow in a logical order. It is a single dense sentence with many clauses, which is efficient but slightly heavy to parse; no sentence 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?

For a one-parameter read-only lookup with an output schema present, the description covers input formats, verification facets, privacy boundaries, and the reporting pointer. Nothing an agent needs in order to call it correctly 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 the single parameter is already documented, so the baseline is 3. The description earns an extra point by adding the 32-character length constraint and restating the two accepted formats in the context of what is being verified.

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 opens with a specific verb+resource ("Checks a document issued on Reciba") and enumerates exactly what is verified: document type, issue date/time, issuer account and e-mail confirmation, counterparty acceptance, and OpenTimestamps status. This is clearly distinguishable from siblings like prepare_document and list_document_types.

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 states the two accepted input forms (the 32-character code under the QR code, or the reciba.com.br/d/ link) and gives a concrete usage scenario ("When a document looks forged or misused"). It stops short of explicitly naming when to prefer a sibling tool, but the verification-only scope is unambiguous.

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