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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the risk profile is known. The description adds real workflow context beyond them: execution must follow a separate confirmation message and the response must be passed verbatim. It could still note irreversibility or what happens on a failed execution, so it stops short of 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 short sentences, each doing distinct work: what it does, what to pass, and when to abstain. The gating condition is front-loaded and 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?

For a two-parameter mutation with no output schema and annotations that already signal destructiveness, the description covers the essential precondition and input discipline. It omits what a successful or failed execution returns, which an agent in a confirmation flow would benefit from knowing.

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 properties already carry descriptions ('Id devolvido por propor_*' and 'palavra por palavra. Nao interprete'). The description restates the same instruction to pass the id and the literal reply, adding emphasis but no new semantics, 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 ('Executa uma proposta') and pins the resource to the id returned by propor_*, which cleanly separates it from the propose_* siblings. An agent can tell it is the execution step of a two-phase flow without reading either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition (client confirmed in another message) and an explicit exclusion with the alternative action ('Se ele nao confirmou claramente, nao chame esta tool: pergunte de novo'). The when/when-not pair is fully specified.

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, destructiveHint=false and openWorldHint, so the safety profile is covered by structured data. The description contributes the returned field set (amount, remaining balance, due date, ownership), which is genuinely useful, but says nothing about behavior when the id is unknown or invalid.

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 short sentence with the resource and lookup key front-loaded and no filler. Every clause (fields returned) earns its place.

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 tool with annotations and no output schema, the description usefully enumerates what is returned, which compensates for the absent output schema. The missing piece is not-found/error behavior, so not a 5.

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 meaning. It only says the lookup is "pelo id", which the property name id_parcela and its uuid format already convey; no detail on whether the id is the installment id versus an account or client id. Barely minimum viable.

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?

"Detalhe de uma parcela pelo id" states a specific verb (detail/fetch) and resource (a single installment), and the phrase "pelo id" signals a single-record lookup in contrast to the listar_* siblings. It does not name any sibling explicitly, so it falls 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 only implied: an agent infers it should call this when it already has an installment id, versus listar_contas_a_pagar when it does not. There is no explicit when-to-use or when-not-to-use statement and no mention of the alternative list 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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety and repeatability are covered structurally. The description adds that results are broken out per account with a total, which is useful behavior beyond the annotations, but says nothing about freshness of the data (real-time vs. cached), permissions, or response structure.

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 with zero padding: the first states what is returned and at what granularity, the second gives the user-intent trigger. It is front-loaded and every clause carries information an agent can use.

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-only tool with no output schema, the description usefully describes the shape of the result (per-account balances plus a total). Only the absence of any note on data currency or what an empty account list looks like keeps it short of fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4 and no schema meaning is left unexplained. The description correctly implies no input is required, matching the empty object schema.

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 precisely (current balance of each financial account, bank and cash) plus the aggregate total, which is a concrete result rather than a restatement of the name. It does not explicitly contrast itself with siblings like listar_contas_a_pagar, but the domain (account balances vs. payables/receivables) is distinct enough for an agent to disambiguate.

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 supplies one concrete usage trigger - the user question "qual meu saldo?" - which maps intent to tool well. It offers no alternatives, prerequisites, or when-not guidance, and there is no routing to listar_contas_a_pagar/a_receber for agents asking about pending amounts instead of balances.

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, non-destructive and openWorld, so the safety profile is covered. The description adds only that results carry an 'id' and that the data feeds propor_lancar_conta; it does not explain whether the category set is stable/tenant-specific (openWorld) or whether the id is required downstream.

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 tightly-packed sentences with the resource and its purpose front-loaded and no filler. The telegraphic style loses a little readability 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?

For a simple read-only list tool with one optional enum parameter and no output schema, this is close to sufficient, but it never mentions the no-filter default behavior or what fields besides 'id' come back, which matters since propor_lancar_conta presumably consumes 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?

Schema description coverage is 0%, so the schema only shows an unnamed enum RECEITA/DESPESA with no explanation. The description partially compensates by glossing the values as 'receita/despesa', but does not state that 'tipo' is optional (0 required) or that omitting it returns all categories.

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+resource ('Categorias financeiras') and states the returned field ('com id') plus the domain (receita/despesa), which distinguishes it from the account/receivable/payable listing siblings. It stops short of anything beyond that one line, but an agent can still tell what it returns.

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 one concrete usage cue: it is 'Necessario para propor_lancar_conta', implying it should be called before proposing an entry, which is genuinely useful routing. It does not say when not to call it, whether the 'tipo' filter should be used for a specific flow, or what happens when it is omitted.

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?

The annotations already declare this as readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds that results span both clients and suppliers, but it does not explain pagination behavior, result limits, or what happens with empty matches, leaving behavioral gaps beyond the annotations.

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, front-loads the searchable scope, and ends with actionable usage guidance. There is no redundant or filler wording.

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 four optional parameters, rich annotations, and no output schema, the description covers the essential purpose and usage context. It could be stronger by noting pagination behavior or clarifying that listar_clientes returns both client and supplier records, but it is largely complete for this tool's complexity.

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 75%, with busca, pagina, and tamanho_pagina documented in the schema, while perfil only has an enum. The description reinforces that busca works by name or document and that results include both clientes and fornecedores, which maps to perfil, but it adds little beyond the schema about pagination or page size.

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 action ("Busca") and resource ("pessoas cadastradas (clientes e fornecedores)"), including the searchable fields name or document. It does not explicitly contrast itself with siblings such as propor_criar_cliente, though the usage sentence helps distinguish it.

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 clear timing guidance: use it before launching an account or registering a client. It does not state when not to use it or name an alternative lookup tool, so it falls short of the strongest usage 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?

Adds real context beyond the annotations: the default window is the current month, and the response carries aggregate totals for the whole filtered set in extra.totais (not just the page). It also flags that busca matches free text typed by third parties and must be treated as data, not instructions, which matters given openWorldHint=true; Pagination behavior itself is left to the schema.

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 resource, then the default window, then the usage example, then the safety note — a sensible ordering with no filler. The final safety sentence is slightly run-on but carries non-obvious information, so it earns its place.

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?

No output schema exists, and the description compensates by naming the key return field (extra.totais) and its aggregate semantics. For a read-only filtered list with 6 optional parameters covering 83%, the remaining gap is pagination and ordering 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?

Schema description coverage is 83%, so the schema already documents busca, pagina, tamanho_pagina, and the date defaults. The description adds little parameter-level syntax beyond restating that omitting dates means the current month, which the schema already says.

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 ('Lista contas a pagar (parcelas)'), plus the ordering key ('por vencimento'). The distinction from the sibling listar_contas_a_receber is carried only by the resource name itself, not by explicit wording.

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 usage trigger ('Use para "quanto tenho a pagar esta semana?"') and clarifies the no-dates fallback to the current month. It does not name alternatives such as consultar_parcela for a single parcela or consultar_saldo for aggregates, so exclusions are left implicit.

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 behavior, so the description only needs to add context. It does: it discloses the default current-month window and where totals land (extra.totais), and it warns that free-text fields are third-party data rather than instructions, which is useful prompt-injection guidance. It does not mention pagination behavior or ordering of results.

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?

It is short and front-loads the resource, filter dimension, and aggregate behavior. The injection warning is a distinct concern appended at the end, but it is one sentence and earns its place.

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 list tool with a well-described six-parameter schema and no output schema, the description covers scope, default window, and the shape of aggregate output. The main omission is how results are ordered and what each parcela record contains.

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 83%, so the schema already documents most parameters including date formats and page-size enum. The description adds only the default date-window semantics ('Sem datas, cobre o mes corrente'); it says nothing about status values or busca matching, so it stays at the 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?

The description states a specific verb and resource ('Lista contas a receber (parcelas) por vencimento') plus the aggregate behavior ('totais do filtro inteiro em extra.totais'), which distinguishes it from listar_contas_a_pagar and consultar_parcela.

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 concrete usage scenario ('quanto tenho a receber esta semana?') and states the default window when no dates are supplied. It does not explicitly name the sibling alternatives (listar_contas_a_pagar, consultar_parcela) or state when not to use it.

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?

The annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is already partly structured; the description usefully adds that nothing is persisted here, that internal duplicate search can refuse the proposal, that similar names return candidate lists, and that records cannot be deleted via this path. What it does not disclose is whether the pending proposal itself is stored or only returned as text, nor what the returned text contains — a meaningful gap given there is no output schema.

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?

Content is front-loaded and dense: the negated verb, the follow-up tool, the search rules, and the deletion caveat each appear once. The all-caps emphasis and telegraphic clauses slightly hurt readability, but no sentence is redundant.

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 6-parameter, two-step proposal tool with no output schema, the description covers the workflow, the refusal conditions, and the confirmation gate that an agent must not skip. Remaining gaps are the two undocumented parameters and the content of the text it returns to show the client.

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 only 33%, so the description must carry weight; it does explain the semantics of confirmo_que_e_novo (only true after asking the owner) and ties documento and nome to the duplicate/similarity refusal rules. However, email and perfil receive no explanation in either place, leaving a real coverage 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?

"Prepara o CADASTRO de um cliente ou fornecedor novo" names a specific resource and makes the non-obvious verb precise by immediately negating the naive reading ("NAO cadastra"). It also distinguishes itself from the sibling confirmar_acao, which it says must be called afterwards.

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 (new client or supplier), when-not (it does not persist anything), and the required follow-up tool (confirmar_acao). It also states the preconditions for proceeding — a clean document search and, for similar names, explicit owner confirmation plus confirmo_que_e_novo=true.

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 readOnlyHint=false but destructiveHint=false and idempotentHint=true; the description reconciles this by explaining the tool only prepares and that the returned text (with saldo antes e depois) is meant to be shown to the client, which is meaningful context beyond the hints. It does not cover what happens to the pending proposal (expiry, one-at-a-time limits) or error behaviour.

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, no filler, with the critical non-obvious fact (it does not actually settle) placed immediately after the purpose statement. Front-loading is correct and the negation is emphasised so it cannot be skimmed past.

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 preparatory, non-destructive step in a two-call workflow with no output schema, the description supplies the essential contract: what it returns (client-facing text plus before/after balance) and that confirmar_acao must follow. Gaps remain around the second-step handoff (what to pass to confirmar_acao) and the two undocumented identifiers.

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 60% and the description says nothing about any of the five parameters. id_parcela and id_conta_financeira are documented nowhere, and nothing explains whether valor may be partial or how data_pagamento defaults interact with the balances shown; only the vague parenthetical "paga/recebida" hints at valor.

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 ("Prepara a baixa de uma parcela") plus the clarifying gloss "registrar que foi paga/recebida", and immediately distinguishes itself from the actual settlement by naming confirmar_acao as the follow-up. An agent can tell this apart from consultar_parcela and confirmar_acao without opening any 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 says "NAO da baixa: exige confirmar_acao depois", which is a clear when-to-use / when-not-to-use rule tied to a named sibling. It lacks only an explicit statement of the converse case (e.g. when to skip the proposal and call confirmar_acao directly), but the sequencing constraint is unambiguous.

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 real behavior beyond the annotations: the tool produces display text rather than committing the entry, and confirmation is a separate human-in-the-loop step. There is mild tension with readOnlyHint=false ('NAO lanca nada' reads as no-op, but the call presumably persists a proposal), though this is a staged-write pattern rather than a contradiction. It does not explain whether repeated calls overwrite a prior proposal, which matters given idempotentHint=true.

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, zero filler, with the most dangerous misconception ('does it actually create the account?') negated up front via capitalization. The next-step instruction follows immediately in reading order.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and eight parameters, the description focuses on the highest-risk aspect – that this is a staging step requiring confirmation – which is the right allocation of space. It leaves minor gaps on default behaviors (e.g. data_vencimento defaulting to today) and on what the returned text looks like, but those are recoverable from the schema.

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 63% and five of eight parameters carry inline descriptions, including the audit-critical 'mensagem_do_cliente' rule about literal quoting. The description itself adds no parameter guidance, so the baseline 3 applies – it neither compensates for nor worsens the remaining undocumented fields (tipo, descricao, id_conta_financeira).

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 ('Prepara o lancamento de uma conta a pagar ou a receber') plus the concrete deliverable ('devolve o texto para MOSTRAR ao cliente'). The closing sentence distinguishes it sharply from the sibling confirmar_acao, so an agent can separate the two-step flow without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit negative constraint ('NAO lanca nada') and the exact condition and tool that follows ('so depois que o cliente confirmar e que se chama confirmar_acao'). This is a when-to-use-and-when-not in two lines; the only unaddressed edge is when to prefer propor_dar_baixa or propor_criar_cliente, which target clearly different resources.

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