SignaBras Certificados Digitais

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

Goes well beyond the annotations by disclosing the required Authorization: Bearer sb_live_... operator key on the HTTP call, that only Pix is supported, and the responsibility split (holder pays and does the videoconference; the agent never pays). It adds real operational context the annotations (readOnlyHint=false, openWorldHint=true) do not convey. Minor gap: it does not reconcile the schema's idempotency_key (24 h dedupe) with the idempotentHint=false 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?

Front-loads the purpose in the first sentence and keeps each following sentence to a distinct load-bearing point (Pix-only, pre-call confirmation, auth header, payment responsibility). Slightly dense and the parenthetical detail adds length, but nothing is wasted or redundant with the 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 12-parameter mutation tool with no output schema, the description helpfully characterizes the return payload (Pix artifacts + tracking link) and the auth prerequisite. Combined with 100% schema coverage, an agent has what it needs; only the idempotency nuance is left implicit vs the schema's idempotency_key.

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 every one of the 12 parameters is already documented inline (CPF, CNPJ, IBGE code, product_slug source, idempotency_key behavior). The description adds only a general 'confirm produto, preço, requisitos e dados' prompt, which does not extend meaning beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 ('cria um pedido de certificado em nome do titular') and explicitly lists what it returns (Pix QR Code copy-paste, image, validity, tracking link). This distinguishes it cleanly from the read-only siblings (get_order_status, get_product, search_products), which none of them create orders.

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?

'Antes de chamar, confirme com o titular produto, preço, requisitos e dados' gives a clear precondition before invocation, and 'Pix-only' bounds the payment method. It does not name explicit alternatives or when-not-to-use cases, but for a dedicated create endpoint there is no competing sibling to route between, so the guidance is solid though not exhaustive.

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 establish readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable context not covered by annotations: the same-API-key access restriction and the privacy guarantee (sem dados pessoais do titular). It does not detail rate limits or error behavior, but the added scope and privacy notes are meaningful.

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 sentences with no wasted words. The first front-loads the core action and returned data; the second efficiently adds scope and privacy constraints.

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-parameter tool with full annotation coverage and no output schema, the description is complete. It explains what is returned and states the key access limitation, leaving no critical gap for an agent 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?

Schema description coverage is 100% for the single order_uuid parameter, so the schema already documents the input. The description contextualizes the order as one created by create_pix_order but adds no syntax or format details beyond the schema, so the 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 (consulta), resource (status de um pedido), and ties it directly to create_pix_order, its creation sibling. It also enumerates the returned components (pagamento, videoconferência, emissão, Pix ativo, links), making the tool's scope unambiguous against the other 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 description implies usage by specifying that the order must have been created by create_pix_order and that only same-API-key orders are accessible. However, it does not explicitly state when to use this tool versus alternatives or provide exclusions beyond the API-key constraint.

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 closed-world, so safety is covered. The description adds real context beyond that: 'Conteúdo estável' signals the content changes rarely (useful caching/staleness cue) and 'com links para as páginas completas' discloses that the return contains references to fuller pages.

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 sentences, front-loaded with the resource name followed by the coverage list, which is the information an agent needs for selection. The topic enumeration is long but each item earns its place as a routing signal.

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 parameterless, read-only content-retrieval tool with no output schema, the description supplies enough: what topics exist, that the content is stable, and that fuller pages are linked. Only the precise return shape is unspecified, which is a minor gap 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?

The tool takes zero parameters, which is the baseline-4 case. No parameter meaning needs to be supplied, and the description does not falsely imply any filtering or query options.

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 the resource (SignaBras policies) and enumerates the specific topics it covers (refund/warranty, issuance requirements, renewal, deadlines, payment methods, terms, privacy, contact), so an agent can tell it apart from the order/product siblings without opening a schema. The retrieval verb is only implied via the tool name rather than stated, which keeps it short of a 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?

Usage is implied by the topic list: an agent can infer this is the source for policy questions. However there is no explicit when-to-use statement, no mention of when it is not appropriate, and no reference to any alternative (there is none, since siblings are all product/order tools) - so it stays at minimum viable.

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, openWorldHint and idempotentHint, so the safety profile is covered. The description adds genuine value beyond them by inventorying the payload an agent will receive (current price, validity, requirements, mandatory order fields, URLs), which substitutes for the absent output schema. It does not cover not-found/error behavior, which would be a nice 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?

A single front-loaded sentence: verb, resource, lookup key, then a compact colon-separated inventory of return fields. No filler, nothing to trim.

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 full annotation coverage, the description is nearly sufficient: it explains the lookup key and enumerates the return content in place of a missing output schema. It stops short of describing failure modes (invalid/unknown slug) or routing to search_products.

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 there is only one parameter, whose schema entry already explains the slug with an example ('e-cpf-a1-12m'). The description's 'pelo slug' adds nothing beyond the schema, so 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 ('Detalha um certificado') plus the lookup key ('pelo slug'), and enumerates the facts returned (price, validity, requirements, required order fields, URLs). Clear on its own, but it never distinguishes itself from the sibling search_products, so an agent must infer the read-detail vs. list distinction.

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 gives no when-to-use statement, no prerequisites, and no mention of alternatives. With search_products as a sibling, the obvious question of whether to browse or fetch a single product by slug is left entirely to inference; only the required 'slug' argument hints at post-search usage.

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, openWorldHint, and idempotentHint, so safety is covered. The description adds domain context: the catalog scope (only A1, e-CPF/e-CNPJ), which is perhaps more a constraint than behavior. It doesn't describe result volume, pagination, or whether results reflect live inventory, but with annotations covering the safety profile a 3 is appropriate.

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 dense sentence that front-loads the resource and scope, with a short second clause for the filter. No filler, though the parenthetical about A1 types is slightly information-dense but earns its place by delimiting the catalog.

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 search with an output schema absent, the description should convey what results include (it does: price, validity, requirements, required fields) but doesn't say how many, whether paginated, or what to do next. Annotations cover safety, but return-shape hints are thin; adequate but with clear gaps.

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 query parameter is fully documented in the schema. The description gives helpful examples of filter values ('cnpj', 'pessoa física', 'mei') that illustrate expected inputs, adding marginal value over the schema. Baseline 3 is correct when the schema does the heavy lifting. Note the examples may leak into data values rather than keys.

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: lists digital certificates for sale with price, validity, requirements. It also scopes the catalog (only A1, e-CPF and e-CNPJ), which distinguishes it from get_product. It doesn't explicitly contrast with get_product, but the plural/list nature of search vs. single-item get is reasonably clear.

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?

No when-to-use guidance. It doesn't say to use this search to discover products before calling get_product with an ID, nor when to prefer it over get_policies. The optional filter hint implies discovery usage but no explicit routing.

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