Stone Vendas

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

Annotations already declare the tool non-read-only, idempotent, and non-destructive. The description adds useful behavioral details: with no args the tool returns a link, with a token it performs a session-only login, and the config-header method gives a permanent non-expiring connection. It does not mention error cases or what happens on repeated token submissions, but the core behavior is disclosed.

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 compact and front-loads the purpose before explaining the two authentication paths. The flow is a bit run-on and could be broken into bullets, but every sentence contributes useful 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 tool with one optional parameter and no output schema, the description is largely complete: it covers the user flow, token passing, link retrieval, and permanent versus session-only behavior. It does not specify the exact return value for the token-call success case, which is a minor 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 coverage is 0%, so the description must carry the meaning. It does so by showing the exact invocation `{ token: "<jwt>" }` and explaining that calling with no args returns the link. This clearly conveys that the token parameter is optional and what it represents.

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 communicates that this tool handles authentication: it provides a login link when called with no arguments and accepts an access token for session-only login. It goes beyond the title 'Authenticate' by describing the actual login flow, though it does not name any sibling tools to distinguish itself.

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 explicitly recommends the permanent config-header approach as the best alternative, and states that pasting a token here is for session-only login. It also gives the no-args invocation as the way to obtain the link, providing clear when-to-call 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, so the safety profile is covered. The description adds meaningful behavioral detail beyond the annotations by explaining the exact conditional return states: authenticated:true with empty pending[] when connected, and connect_url with per-install URLs when credentials are missing. This gives an agent useful expectations about the response without contradicting 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 concise and front-loaded with the core purpose, then provides essential conditional details in the following sentences. Every sentence contributes meaningful information with no redundancy 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 tool's simplicity, zero parameters, and rich annotations, the description is complete for an agent to invoke it correctly. It explains both primary outcomes and the relevant returned fields, which is sufficient since there is no output schema and the tool has no complex inputs.

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 has zero parameters, so there are no parameter semantics to clarify. The baseline for a zero-parameter tool is 4, and the description adds relevant context about the returned status fields even though no parameters exist.

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 states a specific verb and resource: 'Returns connection status and URLs.' It also specifies conditional outcomes, such as returning authenticated:true when all providers are connected and connect_url when credentials are missing. However, it does not explicitly name or differentiate itself from the sibling tool authenticate, leaving some ambiguity about scope.

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 this tool is for checking connection status and retrieving URLs, and it gives conditional behavior for connected vs. missing-credential states. It does not explicitly state when to use this tool versus authenticate or other siblings, nor does it mention when not to use it. The usage context is implied 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 (readOnlyHint=false, openWorldHint=true) only signal that this tool has write and open-world aspects; the description adds substantial behavioral context on top: invoke runs tools one-off without installing or bloating the tool list, writes require workspace owner/admin, search/describe flag installed_in_toolkit vs installed_in_workspace, and publish_prompt returns a login-free shareable link. It discloses side effects (install adds tools to future sessions, invoke does not), permission requirements, and retry behavior after payment/connect links. This is rich disclosure well beyond what the annotations 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?

The description is long (~300 words) but every sentence earns its place for a tool with 14 actions. It is front-loaded: the purpose statement, capability examples, and core flow come first, followed by the KEY behavioral disclaimer, conditional auth/payment handling, usage rules, permissions, and finally the prompt-library addendum. The 'KEY:' marker highlights the most decision-relevant fact, and the prompt-library section is necessary to explain why the schema contains 11 prompt_* parameters with otherwise zero documentation.

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 14-action, 23-parameter tool with no output schema, the description is remarkably complete: it explains the main flow, edge cases (not installed, missing credentials, empty wallet), permission requirements, and the secondary prompt-library domain. But gaps remain: the 'resume' action in the enum is never mentioned, and the immediate and conversation parameters' semantics are undocumented. Several action outputs are unspecified (search results shape, list_tools output, get_prompt return), and since there is no output schema to fill that gap, the description carries that burden partially but not fully.

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 and 23 parameters, the description carries the full burden and does compensate for the most critical parameter — it maps the action enum values to concrete workflows (search discovers, describe returns MCP profile with tool_id, invoke runs, subscribe/cancel handle billing). It also grounds mcp_id/tool_id (the describe→pick tool_id→invoke flow) and the prompt_* family as a cohesive library sub-domain. However, several parameters remain unexplained in both schema and description — immediate, conversation, tier_slug, cancel_reason semantics, report_context, request_details — so the compensation is strong but not complete.

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 exactly what the tool is ('the in-platform catalog of every MCP/tool, AND the way to run them') and enumerates its 14 actions across two clear domains: MCP discovery/execution and the prompt library. It names each action with its role (search discovers, describe profiles, invoke runs, install persists), which fully disambiguates it from the stone_vendas_* sibling tools that are individual MCP endpoints rather than the platform catalog. The 'Core flow: action=search → describe → invoke' sentence anchors the multi-action tool around a single understandable purpose.

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?

Provides explicit when-to-use guidance: 'use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use,' and describes the conditional flow for auth and payment ('If the MCP needs a credential/login, invoke returns a connect link; if it is paid and the wallet is empty, invoke returns a checkout/top-up link... then you retry'). It also distinguishes the prompt-library actions from MCP actions and names list_tools as the way to see what is callable right now. The alternatives and their selection conditions are stated directly rather than left to inference.

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: idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds the reproduction-focused instruction about the conversation array, which is useful context but does not disclose significant additional behavioral traits such as what happens after submission.

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 a single, front-loaded sentence that states the tool's purpose and immediately gives the key usage instruction. Every clause earns its place and there is no redundancy.

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 tool is simple and annotations cover basic side-effect characteristics, making the description adequate for basic invocation. However, the 'context' parameter is left unexplained and there is no mention of what happens after reporting, so the description is not 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?

Schema description coverage is 0%, so the description must compensate for the undocumented parameters. It clarifies that 'conversation' should contain recent messages for reproduction, but it does not explain 'context' or elaborate on the required 'message' parameter, leaving a meaningful semantic 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 ('Report') and resource ('a bug, missing feature, or send feedback'), making the tool's purpose immediately clear. It also distinguishes itself from the sibling tools, none of which appear to be a feedback/reporting channel.

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 clearly identifies when to use the tool: when there is a bug, a missing feature, or general feedback. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to route these cases appropriately.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'current' qualifier but does not disclose output format or whether it accesses external state; with strong annotation coverage, this is adequate.

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 entire description is a single clear sentence with no filler. It front-loads the action and object and earns every word.

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 utility tool, the description is nearly complete. It does not specify the shape of the returned version output, but the simplicity of the tool makes that a minor gap rather than a meaningful blocker.

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 has zero parameters, so there is no parameter burden to document. The schema confirms no inputs are needed, and the description correctly implies an unconditional, configuration-free 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?

The description states a specific action ('Show') and a precise resource ('current MCP platform and adapter versions'), making the tool's purpose immediately clear and distinguishable from siblings like authenticate or report_bug.

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?

For a zero-parameter utility tool, the description clearly implies the appropriate usage context: when the agent needs version information for the platform or adapter. It does not explicitly name alternatives, but the trivial informational nature makes that omission minor.

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 description adds value beyond the annotations by disclosing that the output is a complete daily file, already converted from XML to JSON, and enumerating the contained blocks. The annotations already cover read-only, idempotent, and non-destructive behavior, so the description supplements rather than repeats that safety profile.

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 sentences with no filler: the first sentence front-loads the core resource, scope, conversion status, and content blocks; the second sentence gives targeted usage guidance. Every phrase 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?

With no output schema and no parameter descriptions in the schema, the description carries a heavy burden. It describes the output contents well but fails to document the two input parameters, their expected formats, or the role of the optional account field. An agent could select the tool but would likely guess at parameter formatting.

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 compensate for both parameters, but it only vaguely implies that 'data' refers to the single day being queried. The 'account' parameter is not mentioned at all, and no date format or account identifier format is provided. This leaves parameter meaning largely inferred from the tool description rather than explicitly documented.

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 what the tool provides: a complete single-day reconciliation file already converted from XML to JSON, including all major blocks. It lacks an explicit action verb like 'retrieves' or 'returns', but the object and scope are unmistakable, and it distinguishes itself from period-based tools.

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 explicitly tells the agent when to use this tool: when the period-based tools do not cover the field needed. This implies a clear alternative path, though it does not name the specific sibling tools or list concrete 'when not to use' scenarios.

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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond annotations: daily file generation, data freshness timing, default end date, and the 92-day request cap. No contradiction with 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?

Three compact sentences with no filler: the first states the resource and output fields, the second explains data availability and defaults, and the third gives the hard constraint. All sentences earn their place and key constraints are front-loaded.

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 there is no output schema, the description helpfully names the returned data elements and operational constraints. It is missing explicit date format expectations and more precise account-parameter behavior, but for a read-only, idempotent lookup tool the provided context is largely sufficient.

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 burden. It communicates the period concept, the 92-day limit, and the default through yesterday, and 'conta Stone' maps to the account parameter. However, it does not explicitly define date formats, whether params are optional, or exactly how account defaults behave, 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?

The description clearly identifies the tool's domain: cancellations, chargebacks, and chargeback re-presentations for the Stone account, and lists the returned fields (NSU, value, dates, reason). This unambiguously differentiates it from siblings like stone_vendas_liquidacoes and stone_vendas_recebiveis. Although there is no explicit verb, the intent to return this data is unmistakable.

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 provides concrete operational guidance: Stone produces one file per day, the current day is only ready after 5am the next day, the default range goes through yesterday, and calls are limited to 92 days. It does not explicitly compare against alternatives, but the context is clear enough for an agent to know when and how to call 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the scope boundary 'conectados neste install' and specifies output fields, but does not disclose authentication needs, filtering behavior, or possible error conditions.

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 a single, front-loaded sentence with no filler. Every word contributes to the core purpose and expected output.

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, the description covers the return contents (id and apelido), but the undocumented `account` parameter and the lack of usage context leave a meaningful gap. Since there is no output schema, the description should have explained the parameter more thoroughly.

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 only parameter, `account`, is a bare string with no schema description (0% coverage), and the tool description never mentions it. The description does not compensate for the missing parameter semantics, so an agent cannot tell whether `account` filters, selects, or is needed in some cases.

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 uses a specific verb ('Lista') and a specific resource ('StoneCodes/estabelecimentos Stone conectados neste install') and explicitly mentions the output fields (id and apelido). This is clearly distinct from sibling tools like stone_vendas_listar or stone_vendas_recebiveis.

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 guidance is given about when to use this tool versus alternatives, nor any prerequisites or exclusions. The description simply states what the tool lists, leaving the agent to infer the appropriate use case.

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 description says the tool discards cache and forces regeneration, which is a state-changing operation, while annotations declare readOnlyHint=true. This is an annotation contradiction. Although it adds useful non-effects and quota details, the contradiction forces a score of 1.

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 sentences, front-loaded with the core action and usage trigger. The quota warning earns its place. Minor typo ('regerar' for 'regenerar') and slightly run-on first sentence keep 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?

The description covers purpose, trigger, non-effects, and quota, but with no output schema and no parameter semantics, it leaves the agent guessing about inputs, return value, and how to confirm the cache was regenerated.

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 gives no parameter-level detail. 'Período' loosely relates to data_inicio/data_fim and the tool name relates to account, but an agent cannot tell the expected date formats, which account identifier to provide, or optionality from the description.

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 uses a specific verb ('Força a Stone a regerar o arquivo de conciliação') and names the exact resource and side effect (discarding the cached extract). It also gives a concrete trigger condition, distinguishing this cache-refresh tool from the other stone_vendas_* 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?

It explicitly states when to use the tool ('Use quando os números não baterem com o painel da Stone') and warns against repeated sequential calls because of rate-limit quota. It doesn't name alternative sibling tools, so it stops short of a full when-to-use/when-not-to-use map.

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, which already indicate read-only, idempotent, and non-destructive behavior, the description adds useful behavioral details: data availability lag, default date window, maximum range per call, and that only effectively deposited values are returned. No contradiction with 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 three sentences long, front-loaded with the core purpose, and contains no filler. Each sentence adds value: what the tool returns, why it is used, and the availability/range 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?

With no output schema and no parameter descriptions, the burden falls on the description. It adequately covers return content and key constraints, but lacks explicit parameter semantics and output formatting details. It is viable but leaves clear gaps for an agent trying to construct exact arguments.

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 schema has 0% description coverage, so the description must compensate. It mentions 'período' and 'conta bancária favorecida' and gives constraints like 'Máximo de 92 dias por chamada', but it does not explain the expected date formats, whether dates are inclusive, how account values work, or the implications of all parameters being optional.

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 exactly what the tool returns: Stone settlements for a period, the effectively deposited amounts, the total value, and the receiving bank account. It also distinguishes this tool from siblings by noting it is 'a ponta que fecha com o extrato bancário'.

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 usage context: this is the tool that reconciles with the bank statement. It also provides temporal guidance, such as same-day files being unavailable until after 5h the next day, the default range going up to yesterday, and the 92-day maximum per call. It does not explicitly name alternatives or exclusions, but the context is strong.

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?

Even though annotations already mark the tool as read-only, idempotent, and non-destructive, the description adds material behavioral context: one line per transaction, the exact fields returned, the daily file processing delay, and the 92-day maximum range. No contradiction with annotations 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 dense but not wasteful: the first sentence lists the returned fields and the second conveys data availability and range limits. It is slightly long and could be better separated into scannable sentences, but every part adds 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?

The description covers the output fields well and gives important operational constraints, but it lacks guidance on several input parameters, omits a valid status from the schema enum, and there is no output schema to compensate. An agent would need to infer some parameter semantics from names and the field list.

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 compensate, but it only loosely maps 'período' to data_inicio/data_fim and partially lists allowed values for status and forma_pagamento. It omits the 'registrada' status present in the schema, and provides no meaning for 'limite', 'account', or 'bandeira' as parameters.

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 uses a specific verb ('Lista') and identifies the resource ('vendas do adquirente Stone no período'), clearly distinguishing it from sibling tools like resumo or liquidacoes by explaining transaction-level detail and the exact fields returned. It is unambiguous about what the tool does.

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 provides clear context about when the tool is appropriate, including the daily file availability delay and the default range ending yesterday. However, it does not explicitly name alternatives or state when not to use this tool relative to siblings such as stone_vendas_resumo or stone_vendas_liquidacoes.

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?

This description goes well beyond the annotations: it reveals the asynchronous behavior, the per-CNPJ file delivery mechanism, the possibility of pending days taking up to 30 minutes, and the requirement for the Document connection field. Annotations already mark it read-only and idempotent, and the description adds substantial behavioral context without contradicting them.

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?

Every sentence earns its place: it front-loads the returned fields, then explains the asynchronous workflow, retry guidance, connection requirement, and time limit. There is no filler or repetition.

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 tool with no output schema, the description is fairly complete: it lists the output data fields, explains the pending-days behavior, and gives practical constraints. It could be more complete by explaining the optional input parameters, but an agent can still use it correctly for the main use case.

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 partially compensates by explaining the period concept (data_inicio/data_fim) and mapping status to paid/canceled. However, it does not clarify the meaning of limite, account, or apenas_maquininha, and the required Document field is a connection setting rather than an input parameter.

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 states that the tool returns Pix sales from Stone's card machine for a period, listing the exact data fields (date/time, value, fee, status, terminal, Pix key, e2e ID, payer data). It also differentiates itself from sibling sale tools by explaining the asynchronous file-based behavior specific to Pix.

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 provides clear usage context: it requests missing files, returns ready ones, lists pending days, and advises calling again later if days are still processing. It also states the connection requirement (Document field) and the maximum 31-day window. It does not explicitly name alternatives or conditions for choosing another sibling, so it stops short of a 5.

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 destructiveHint=false; the description adds valuable behavioral context about data freshness, file availability timing, and the 92-day cap. It also previews the response shape via 'detalhadas e totalizadas por data'. It does not cover empty-result or error behavior, but the annotations lower the burden.

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 dense Portuguese sentences carry only essential information: purpose, data freshness constraint, and maximum range. There is no filler, repetition, or irrelevant context. The most decision-relevant facts are placed prominently.

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 date-bounded query, the description covers the returned data, the effective data latency, and the maximum call window, which is enough for most real usage. The absence of an output schema is partially mitigated by the mention of per-date detail and totals. The remaining gap is the undocumented meaning and format of the account 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 schema has 0% description coverage for its three string parameters, so the description must compensate. It clarifies that data_inicio and data_fim form a date window limited to 92 days with a default ending yesterday. However, it does not explain the account parameter or the expected date format, leaving a meaningful 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 explicitly defines the tool as Stone's receivables agenda: unpaid installments with expected payment dates, detailed and totalized by date. The phrase 'ainda não pagas' semantically distinguishes it from sibling tools like stone_vendas_liquidacoes or stone_vendas_cancelamentos. The purpose is unmistakable even without an explicit verb.

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 invocation context: Stone's daily file is only ready after 5h of the following day, so data should be expected only up to yesterday, and a single call is limited to 92 days. This helps the agent decide when results are current and when requests need to be split. It does not explicitly name alternative tools for when-not-to-use scenarios.

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 carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description adds substantial behavior beyond them: the one-file-per-day ingestion pattern, the 5h next-day availability rule, the default trailing one-day lag, the 92-day cap, and payment-method scope including Pix na maquininha. None of this is inferable from the schema or annotations, and nothing contradicts 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?

Four dense sentences, each earning its place: purpose and dashboard equivalence, groupings and output metrics, payment-method scope, and operational constraints. The core purpose is front-loaded and there is no filler or repetition of schema 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?

With no output schema, the description's enumeration of returned metrics (quantidade, valor bruto, valor líquido, cancelado, chargebacks) adequately covers the return contract, and the freshness/limit rules cover invocation timing. The main omissions are the undocumented account parameter and the unspecified date input format; otherwise the description is complete for a moderate-complexity read-only summary 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?

Schema description coverage is 0%, so the description carries full documentation burden. It compensates for agrupar_por by listing all valid grouping values, for the date pair by stating the 92-day maximum and the yesterday default, and for incluir_pix by mentioning Pix coverage on the machine. Gaps remain: the account parameter is never explained and no date format is specified for data_inicio/data_fim.

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 pair — 'Totais consolidados das vendas Stone no período' — and identifies itself as equivalent to the dashboard's Resumo de vendas. It enumerates exact grouping dimensions (forma de pagamento, bandeira, dia, status, captura, terminal) and output metrics (quantidade, valor bruto, valor líquido, cancelado, chargebacks), which clearly distinguishes it from siblings like stone_vendas_listar, stone_vendas_pix, and stone_vendas_cancelamentos.

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 clear context: this is the consolidated-summary counterpart of the panel's sales summary, and it gives concrete constraints that govern when results are valid — the daily file is only ready after 5h of the next day, the default window ends yesterday, and the maximum is 92 days per call. It does not explicitly name sibling alternatives or state when not to use it, which keeps it at a 4 rather than a 5.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds concrete behavioral context by specifying exactly what state information is returned (installed MCPs, connection status, accounts, catalog tool counts), which goes beyond the annotations. No contradiction 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 a single, well-structured sentence that front-loads the core purpose ('Returns the current toolkit state') and then lists the specific data points. Every phrase adds information with no filler or repetition.

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, the description carries the burden of explaining return values. It enumerates the major components of the returned state (installed MCPs, their connection status, connected accounts, and catalog tool counts), which is sufficient for an agent to invoke and interpret the result. It does not specify the exact response format or field names, but that is a minor gap for a parameterless read-only status 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?

The input schema is empty with zero parameters, so there are no parameter semantics to clarify. Schema description coverage is effectively 100%, and the description correctly does not invent parameters. Baseline for zero-parameter tools is 4.

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 uses a specific verb ('Returns') and a precise resource ('current toolkit state'), then enumerates the data it covers: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly distinguishes it from action-oriented siblings like 'authenticate' or 'connect'.

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 tool is for inspecting the current toolkit state, so the use case is inferable. However, it does not explicitly state when to use it over alternatives (e.g., 'show_version') or provide any exclusions or prerequisites. The guidance is implicit rather than explicit.

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