Poupa AI

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

Annotations indicate idempotentHint true and readOnlyHint false, and the description adds behavioral details beyond those: it explains the flow of returning a link or accepting a token, and mentions the optional permanent configuration via header, which is not captured in 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, somewhat lengthy sentence but is well-structured with clear separation of the two usage modes. It includes concrete call examples ('{token: "<jwt>"}' and 'no args') and front-loads the primary purpose. It could be slightly more concise, but every phrase adds value.

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?

Despite having no output schema, the description tells the agent exactly what to expect (a link when no args, presumably a success status with token). It also covers the optional parameter, the two login paths, and the recommended configuration approach. For a simple one-param tool with no nested objects, this is 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 only parameter 'token' has zero schema description, but the description fully compensates by explaining it is a JWT for session login and that omitting it yields a login link. This adds crucial meaning beyond the raw type, making parameter usage crystal clear.

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 it is for authentication/login, explicitly mentioning 'log in in the browser' and providing two authentication modes (config-based permanent and session-based token). It distinguishes itself from siblings like 'connect' by focusing on auth, making the purpose unambiguous.

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 usage scenarios: calling with no args to get a login link, or with a token for session-only login, and suggests the best practice of adding a header to the server config for permanent access. It does not explicitly mention when not to use or alternatives, but the context is clear enough for an agent to decide.

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 provide readOnlyHint, idempotentHint, and destructiveHint=false, which cover safety. The description adds behavioral detail about return values in different connection states (authenticated:true vs connect_url). This adds context beyond annotations, but doesn't disclose any side effects or edge cases beyond the states mentioned. No contradiction.

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 only two sentences, clean and efficient. It covers key states and what to expect. No wasted words, but could be slightly more front-loaded with a direct statement of what it does.

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 are no parameters and a simple output, the description is quite complete. It explains both the success and failure states. However, it doesn't describe the format of URLs or whether 'connect_url' and 'per-install URLs' are always present, which could be helpful but is not critical for a status check 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 tool has zero parameters, so schema coverage is essentially 100% and there's nothing to explain. The description adds meaning about what the tool returns in different scenarios, which is useful. Baseline 4 for zero parameters 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?

The description clearly states the tool's purpose: returns connection status and URLs. It distinguishes from siblings like 'authenticate' by focusing on status reporting, not initiating auth. It could be more explicit about being a read-only status check, but the description is specific enough.

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 implicitly conveys when to use it (to check connection status and get URLs) but does not explicitly state when not to use it or compare to alternatives like 'authenticate' or 'toolkit_info'. With no siblings for status checking, it's adequate but could be clearer.

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?

While annotations indicate readOnlyHint=false and openWorldHint=true, the description adds substantial behavioral context: that invoke works even without installation (runs one-off without adding to toolkit), that install makes MCPs permanent, that permission requirements exist ('Writes... require workspace owner/admin'), and that invoke may return connect or checkout links. This complements the annotations without contradiction and explains side effects (e.g., one-off install behind invoke).

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 but necessary given the tool's multi-action nature. It is well-structured: starts with the overall purpose, then explains the core flow, key behaviors (invoke without install), then lists auxiliary actions (list_tools, subscribe, etc.) and the prompt library. Each sentence adds meaningful information; there is no redundancy or fluff. The length is justified by complexity, and information is front-loaded with the most important usage.

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 complexity (23 parameters, no output schema), the description covers the major functional areas: marketplace search/describe/invoke, installation, billing, prompt library, and permission requirements. It explains the primary decision points (install vs invoke) and handles edge cases (auth, payment). Missing details on some parameters (e.g., immediate, tier_slug) and specific return formats, but for a tool this broad, the description is reasonably complete for an agent to use it effectively.

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 23 parameters and 0% schema description coverage, the description must compensate. It does so by explaining the action parameter's enum values (search, describe, invoke, etc.) and the flow linking tool_id and arguments to invoke. It also hints at prompt-related parameters via the prompt library. However, it doesn't individually explain parameters like immediate, tier_slug, prompt_vars, or conversation. Given the high volume, it provides enough for the main workflow but not exhaustive parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly defines the tool as 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It specifies multiple distinct actions (search, describe, invoke, install, etc.) and distinguishes itself from sibling tools by being the central marketplace/hub. The purpose is unambiguous and directly tied to the tool's name and function.

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 explicit usage guidance: it outlines a core flow (search → describe → invoke), explains when to use invoke vs install ('prefer invoke for a single/occasional use'), and notes conditions like credential requirements (returns connect link) and payment needs (returns checkout link). It also differentiates from list_tools and mentions subscribe/cancel for billing, plus alternate actions like request_mcp and report_bug. This exceeds typical guidance by giving clear decision rules.

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 indicate a write operation (readOnlyHint=false), and the description says 'Cria' (creates), so there is no contradiction. The description adds useful context about the required fields and recurring/installment behavior beyond the annotations. However, it does not disclose side effects like authentication prerequisites or potential validation errors, which is a minor gap given annotation coverage.

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: the first states the core action and required fields, the second explains how to achieve specific behaviors (installments vs recurrence). It is front-loaded, concise, and every sentence adds value without fluff.

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 has 9 parameters, no output schema, and moderate complexity, the description covers the required fields and the two most nuanced parameter groups (installments and recurrence). It omits the distinction from the plural sibling (poupa_add_transactions) and any prerequisites like authentication, but for a straightforward creation tool the basic usage is well covered. More context about single vs bulk or error handling would raise completeness, but it is adequate.

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 explains the purpose of 'installments' (parcelar), 'expense_recurrency' (dias), and 'recurrency_array_dates' (lista de datas), which adds meaning beyond the schema. However, it only covers three of the nine parameters and does not explain 'category', 'card_name', 'description', or 'payment_bank', leaving ambiguity for those fields.

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 it creates a transaction with a specific verb ('Cria uma transação'). It distinguishes from the sibling 'poupa_add_transactions' (plural) by implying a single transaction, though not explicitly. The purpose is immediately 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?

The description provides usage guidance for recurring and installment transactions, explaining when to use installments vs expense_recurrency/recurrency_array_dates. However, it does not mention when to use this tool over the sibling 'poupa_add_transactions' (bulk add) or other alternatives, missing a clear exclusion statement.

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 indicate readOnlyHint=false, and the description adds that multiple transactions are created at once and that each item matches poupa_add_transaction's shape. It does not disclose batch-specific behavior such as atomicity, partial-failure handling, duplicates, or return value, so the information is minimally beyond 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?

Two concise sentences that front-load the key purpose ('bulk') and the main constraint (required transactions[]). Every word earns its place, and no excessive or repeated information is present.

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, mutation tool with no output schema and coarse annotations, the description gives a usable but incomplete context. It confirms the bulk input shape but misses output/response format, potential batch size limits, and whether the operation is all-or-nothing. These are important gaps for an agent to know before invocation.

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. It does state that transactions[] is mandatory and that each item follows the same shape as poupa_add_transaction, which helps but still leaves field-level semantics (e.g., date format, value meaning) to the reader to infer from the sibling tool or 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 clearly states the tool's purpose: 'Cria várias transações de uma vez (bulk)' – a specific verb (creates), resource (transactions), and bulk scope. It also references the singular sibling poupa_add_transaction, which distinguishes it from the single-transaction tool.

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 is for multiple transactions at once and notes transactions[] is required. However, it never explicitly says to prefer this tool over poupa_add_transaction when batching, nor does it provide when-not-to-use or alternative conditions.

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 covered. The description adds the scope (user's own banks/accounts) but no additional behavioral details such as sorting, pagination, or whether closed accounts are included. It neither contradicts annotations nor enriches them significantly.

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 short sentence in Portuguese, conveying the complete purpose with no wasted words. Every word earns its place, making it extremely concise and well-structured.

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 zero-parameter list tool with strong safety annotations, the description is adequately complete. It states what is listed (banks/accounts of the user), and no output schema exists, so the return value is implicitly the list itself. Some details like account types or balance inclusion are absent, but they are not essential for this level of 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?

The tool has zero parameters, so there is no parameter burden. The schema coverage is 100% (trivially). For zero-parameter tools, the baseline is 4, and the description does not need to add parameter meanings. It remains neutral.

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' / lists) with a clear resource ('os bancos/contas do usuário' / the user's banks/accounts), which clearly differentiates it from sibling tools like poupa_cards, poupa_get_balance, and poupa_retrieve_transactions. The purpose 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 implies usage: use this tool when you need to list the user's banks/accounts. However, it does not explicitly state when to use this over alternatives, nor does it mention exclusions or provide context about related tools. The guidance is minimal but not misleading.

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

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

Annotations already declare readOnly, non-destructive, and idempotent behavior. The description adds no extra side-effect or behavior details beyond the basic function, but it does not contradict the annotations. Since annotations cover the safety profile, a neutral score 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?

The description is a single, concise sentence that directly states the operation. It contains no unnecessary words or redundant information, achieving perfect conciseness.

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 list operation with no parameters and no output schema, the description is fully sufficient. It tells exactly what the tool does, and there are no additional details required for a user to understand its usage.

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, and the schema coverage is effectively 100% because there is nothing to describe. The description does not need to explain parameters, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Lista os cartões de crédito do usuário' clearly identifies the tool's function: listing the user's credit cards. It explicitly distinguishes this operation from sibling tools like poupa_banks (banks) or poupa_transactions (transactions), making its purpose unambiguous.

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 states what the tool does but does not explicitly mention when to use it in favor of alternatives. However, the sibling context implies it is for credit-card-related queries; still, it lacks explicit guidance on when not to use it or how it compares to other list operations.

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 read-only, idempotent, non-destructive behavior, so the description adds value by confirming the resource scope is user-specific categories. It does not introduce any hidden behavior or contradict 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 a single concise sentence in Portuguese with no filler, directly front-loading the tool's purpose. It is appropriately sized for the operation it describes.

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 list operation with clear read-only annotations and no output schema expectations, the description is complete. The tool's behavior and scope are sufficiently conveyed for an agent to use 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?

This tool has no parameters and its schema is empty, so the baseline of 4 applies. The description requires no additional parameter explanations since there are none to describe.

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 the specific verb 'Lista' and the resource 'categorias do usuário', clearly identifying what the tool does and distinguishing it from other poupa_* tools such as transaction or balance tools. It is unambiguous and sufficiently differentiated.

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?

There is no guidance about when to use this tool versus alternatives, no prerequisites, and no mentions of related tools in the description. The one-sentence description only states the action without clarifying context or exclusions.

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 no behavioral context beyond what the annotations already provide. It does not mention return format, user-specific scoping behavior, or any other runtime characteristics, and the read-only/idempotent/non-destructive traits are already declared in 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 a single short phrase with no filler or redundant information. It is front-loaded and appropriately sized for a simple zero-parameter tool.

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 defaults lookup with strong annotations, the description names the relevant resource and scope. However, the absence of an explicit retrieval verb or usage hint slightly limits completeness.

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 the baseline is 4. The description correctly adds no parameter-specific detail because there is nothing to document.

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 resource: the user's default categories and payment methods ('Categorias e métodos de pagamento padrão do usuário'). It is specific enough to indicate scope and distinguish it from general category or preference tools, though it lacks an explicit verb such as 'returns' or 'lists'.

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?

There is no guidance about when to use this tool versus siblings like poupa_category, poupa_preferences, or poupa_cards. The description provides no usage context, prerequisites, or exclusions.

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 clearly states the tool deletes transactions and even notes it refuses to delete all when the filter is empty. However, the annotation destructiveHint is set to false, which directly contradicts the described behavior. This is a major inconsistency that undermines trust.

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, concise and impactful. It states the action, the critical constraint (non-empty filter), and the accepted filter types without any redundancy or fluff.

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 core behavior (deletion), the filter requirement, and the parameters. It does not mention potential error cases (e.g., no matches) or side effects, but given the absence of an output schema and the concise style, it is reasonably complete. It could benefit from a note about what happens if no transactions match, but that is not critical.

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 description covers all five schema parameters: ids, start_date/end_date (as 'intervalo de datas'), description, and category. It provides meaningful context by explaining they serve as filters. The schema itself lacks descriptions, so this explanation adds value. The explicit non-empty filter requirement also clarifies usage.

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 the tool 'Deleta transações por filtro' (deletes transactions by filter), specifying the action on a resource. It also lists acceptable filters (ids, date range, description, category), distinguishing it from sibling tools that add, update, or retrieve transactions.

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 a key usage guideline: the filter must be non-empty, as the tool refuses to delete everything. It also enumerates acceptable parameter types. However, it does not explicitly contrast with alternative tools for when deletion is preferred over update or retrieval, so it loses one point.

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 well covered. The description adds behavioral context about the date filtering and the default of returning all data when no dates are provided, which goes beyond the schema. No contradictions.

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 sentence, front-loaded with the core purpose, and the date logic is succinctly expressed. Every word earns its place, no fluff.

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 simplicity (2 optional params, no output schema, no nested objects) and rich annotations, the description is largely complete. It explains the grouping dimensions and the date behavior. It could mention that the output is aggregated by month, but that's implicit in the grouping; with no output schema, it's a minor gap, but the description is adequate for a read-only balance query.

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 describes the two parameters only as strings with no format or meaning. The description explains that they are optional dates in YYYY-MM-DD format that limit the window and that omitting them returns all data. This adds value, but since the schema coverage is 0%, the description partially compensates. However, it doesn't clarify the expected format for the date range (e.g., inclusive rollover) or any other specifics, so it stays at a 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 clearly states it retrieves the user's balance, grouped by multiple dimensions (bank, category, payment method, card, type, month), differentiating it from sibling tools like poupa_retrieve_transactions (transactions list) and poupa_banks (bank list). It uses a specific verb ('Saldo do usuário') and resource, making the purpose unambiguous.

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 explains the optional date range and its behavior ('start_date/end_date limitam a janela; sem datas, traz tudo'), which is clear usage context. It doesn't explicitly mention when to prefer this over alternatives, but the grouping purpose implicitly distinguishes it from transaction retrieval tools, and the sibling list provides enough contrast.

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. The description adds only that the data is 'gravadas' (saved), but does not disclose behavior such as return format, pagination, or access requirements.

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 concise sentence with no filler or repetition. It is front-loaded and appropriately sized for a tool with no parameters.

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 verb in the description, the tool does not explain what it returns or how the agent should use the result. The annotations cover safety but not operational completeness.

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 the baseline is 4. The description does not need to explain parameter semantics, and no additional parameter information is required.

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 identifies the resource as 'user memories/notes saved in Poupa AI' but lacks a verb specifying the action (e.g., list, retrieve, manage). It is clear in subject matter but does not fully distinguish itself from sibling tools in terms of operation.

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 provided about when to use this tool versus alternatives such as poupa_preferences or poupa_defaults. The description gives no context for selection or exclusions.

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, and non-destructive behavior. The description adds the context that it deals with user preferences (language, currency, etc.), which is useful but does not elaborate on side effects, error conditions, or return specifics. This adds some context 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 a single, short sentence that efficiently communicates the core subject. It is free of unnecessary details and well-sized for the tool's simplicity.

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 mentions user preferences but does not clarify what the tool returns (e.g., a list of settings, values for language/currency). Since there is no output schema, the description should explain the outcome, but it remains vague. It lacks completeness for a read-only 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?

There are no parameters in the schema, so the description does not need to explain any. The empty schema has full coverage, and the description adds no parameter-related information. Baseline score of 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?

The description indicates the tool relates to user preferences, but it is phrased as a noun phrase rather than an action. It is unclear whether the tool retrieves, updates, or manages preferences. This provides some clarity but lacks a clear verb and explicit 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 gives no guidance on when to use this tool compared to others. It does not mention typical scenarios, alternatives, or prerequisites. Usage instructions are entirely absent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat safety. The description adds behavioral detail: date range format (YYYY-MM-DD), keyword matching (partial, case-insensitive on description), and filtering by card/bank. It doesn't mention pagination or return format, but with no output schema and a read operation, this is acceptable. The description complements annotations 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?

The description is a single concise sentence, which is efficient and front-loaded. It provides all key information in a compact form. It doesn't waste words, though it could be slightly clearer about parameter specifics. For a tool with five parameters, this length is appropriate.

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 complexity (5 optional parameters, no output schema, no enums), the description covers the essential aspects: what it does, how filtering works, and the date format. It doesn't explain return structure, but since there's no output schema and it's a straightforward list operation, the description is reasonably complete. It could benefit from mentioning whether results are paginated or ordered, but overall it's adequate.

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 entire burden for parameter semantics. It explains the keywords parameter (partial match, case-insensitive on description), and mentions card and bank/pagador filters. However, it doesn't detail the date format for start_date/end_date beyond the interval mention, and payment_bank is partially described as 'banco/pagador'. The description adds value but could be more specific about each parameter's format and allowed values, especially since the schema itself is bare with no types descriptions.

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 the tool's purpose: listing transactions in a date range with optional filtering by keywords, card, and bank/payer. It uses a specific verb (retrieve/list) with a clear resource (transactions) and distinguishes itself from sibling tools like poupa_add_transaction, poupa_update_transactions, and poupa_delete_transactions_by_filter.

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 context: it's a retrieval tool with optional filters, and the date range is specified. However, it does not explicitly state when to use this tool versus alternatives like poupa_get_balance or poupa_memories. The presence of complementary tools (like add, update, delete) suggests it's the read counterpart, but that's implicit. It's clear enough for basic usage but lacks explicit 'when not to use' 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?

The annotation readOnlyHint=false already indicates a write operation, and the description adds the crucial context that this is an accounting entry ('movimento contábil') rather than a real transfer. However, it does not disclose idempotency, permission requirements, or side effects on balances.

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 sentence that front-loads the primary purpose and includes essential clarifications without fluff. Every phrase adds value.

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 a simple, non-destructive mutation with no output schema. The description covers purpose, key exclusions, and parameter semantics, but lacks error-condition details and return behavior. Sufficient for its apparent scope.

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 explains 'value' and 'date' (including the default of today), but it does not clarify the expected format or semantics of from_bank/to_bank beyond identifying them as the user's banks/accounts. Partial compensation for the missing schema detail.

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 the tool registers a transfer between the user's own banks/accounts and explicitly distinguishes it from a real bank transfer. The verb 'Registra' and the resource 'transferência entre dois bancos/contas' make the action specific and differentiate it from sibling tools like poupa_add_transaction.

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: it is for accounting movements between the user's own accounts, not real bank transfers. This implies when not to use it, though it does not explicitly name alternative tools.

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 indicate this is not read-only, not idempotent, and not destructive, so the description adds modest context by explaining the update mechanism. However, it does not disclose return behavior, error cases, or what 'passthrough' means, leaving some behavioral ambiguity.

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 concise sentence that front-loads the action and resource, then adds the essential input guidance. No words are 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 mutation tool with no output schema, no parameter descriptions, and a vague 'passthrough' mechanism, the description is too sparse. It lacks details about how filter/changes are structured, whether updates are partial or full replacements, and what happens with invalid or empty 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?

Schema description coverage is 0%, so the description must compensate. It partially clarifies that 'filter' holds target ids and 'changes' holds fields to alter, but it ignores the 'ids' parameter and leaves 'passthrough' undefined. This is insufficient for an agent to confidently construct valid calls.

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 the action ('Atualiza') and resource ('transações existentes'), and specifies the scope ('uma ou mais'). This distinguishes it from sibling tools like poupa_add_transactions, poupa_retrieve_transactions, and poupa_delete_transactions_by_filter.

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 direct usage guidance: put target ids in the filter and provide fields to change via passthrough. It does not explicitly name alternatives or exclusions, but the purpose statement makes the use case clear.

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, idempotentHint=true, and destructiveHint=false. The description does not contradict these. It adds context that the tool expects a conversation array for reproduction, which is useful. However, it doesn't describe what happens after reporting (e.g., does it create a ticket? Does it notify developers? What is the response?). For a read/write operation (since readOnlyHint=false), it could benefit from stating if the message is stored or sent externally. Since annotations exist, the description's additional context about conversation is helpful but insufficient for full transparency.

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 one sentence (with two clauses) and zero waste. It front-loads the purpose ('Report a bug...') and then gives a specific usage hint. Perfectly concise and well-structured.

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 has 3 parameters (1 required), no output schema, and annotations are present. The description explains the core purpose and the conversation parameter's role, but it lacks information about expected output or response, any limitations (e.g., maximum size of message/conversation), and whether it's a fire-and-forget. Given the tool's simplicity, it's adequate but not comprehensive. The description could mention that the tool is for user feedback and not for diagnostic queries, but it's somewhat complete for its purpose.

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 has 3 parameters, but description coverage is 0% (the schema has no descriptions for context, message, or conversation). The description itself explains that 'message' is the report content, 'conversation' is a stringified JSON array for reproduction, and 'context' is a default empty string (likely for additional context). The description's instruction to 'Include the conversation array with recent messages' clarifies the purpose of the conversation parameter beyond the schema's basic types. Since schema coverage is 0%, the description must compensate, and it does for 'message' and 'conversation', though it doesn't explicitly mention 'context' (though 'context' might be implied by the name). Overall, it adds significant meaning over the 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 clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' It identifies the primary actions (reporting and sending) and the target (bug/missing feature/feedback). This distinguishes it from sibling tools like 'poupa_add_transaction' or 'marketplace' which have different purposes. However, it doesn't explicitly differentiate from a potential generic 'feedback' tool, but given the sibling list, it's reasonably distinct.

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 when to use this tool (when reporting a bug, missing feature, or feedback) and even suggests including conversation context ('Include the conversation array with recent messages for reproduction'). However, it does not explicitly state when NOT to use it or mention alternatives. For instance, it doesn't say 'for transaction issues, use poupa_* tools' or similar. The guidance is clear enough for a feedback tool, but lacks exclusions or comparisons.

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, destructiveHint=false, and openWorldHint=false, which cover safety and side effects. The description adds no additional behavioral details, such as whether it includes build numbers or requires connection, but with annotations this is sufficient. No contradiction.

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 sentence that states the verb ('show') and the object ('current MCP platform and adapter versions') with no extra fluff. It is front-loaded and concise.

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, no output schema), the description is complete enough to convey the tool's function. It might benefit from mentioning the exact format of version strings, but for a trivial informational tool this is 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?

The tool has zero parameters and schema coverage is 100% (vacuously). The description adds context about what is being shown (platform and adapter versions), which is meaningful even with no parameters to clarify.

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 the tool shows the current MCP platform and adapter versions, which is a specific verb+resource combination. It clearly distinguishes its purpose from sibling tools like 'toolkit_info' or 'connect', though it doesn't explicitly differentiate 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 implies a simple informational use case but does not explicitly state when to use this versus other informational tools like 'toolkit_info'. There is no guidance on usage context or exclusions.

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 fully covered. The description adds meaningful detail about what state is returned but does not disclose additional behavioral traits such as caching, authentication requirements, or performance characteristics. 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?

A single, tightly worded sentence that leads with the action and resource, then expands with a list of the returned elements. Every clause earns its place and there is no redundant phrasing.

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 introspection tool, the description fully covers what the tool does and what information it returns. No output schema exists, but the description gives sufficient detail about the return content, and the annotations plus sibling context complete the picture.

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, and the input schema is empty. The description needs to provide no parameter-level detail, and the baseline for zero-parameter tools is 4; it meets that baseline cleanly.

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 names a precise resource ('current toolkit state') with enumerated content: installed MCPs, connection status, accounts, and catalog tool counts. This clearly distinguishes it from siblings like authenticate, connect, or show_version, which handle different concerns.

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 implies this tool is for inspecting the overall toolkit state, making its usage context obvious. It does not explicitly list alternatives or exclusions, but the nature of the tool is simple and self-evident, so context alone is enough.

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