Next MCP

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

Discloses key behaviors beyond annotations: non-expiring vs session, how to obtain token. No contradiction with annotations (idempotentHint=true matches no mutation).

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?

Single paragraph, efficient, but could be broken into clearer sections (e.g., two options). Still well-structured for the information density.

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?

Fully covers behavior for a simple authentication tool with no output schema. Leaves no doubt about usage and outcomes.

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?

Adds significant meaning beyond schema: explains the 'token' parameter is for session login, and omitting it returns a link. Schema has 0% coverage, so description fully compensates.

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?

Description clearly states the tool is for authentication, with specific verb 'authenticate' and resource 'access token'. Distinguishes from sibling tools (finance-related, connect) by its unique role.

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 clear when-to-use: for IDE agents, with two explicit options (permanent via config, session via pasting token). Also explains calling with no args to get the link, leaving no ambiguity.

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. The description adds value by detailing the return structure for different connection states, which is beyond what annotations provide.

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 efficient sentences that convey all necessary information without redundancy. Front-loaded with the key purpose.

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 zero parameters and no output schema, the description covers both possible states (all connected vs missing credentials) sufficiently. No additional context is needed.

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?

No parameters exist, and schema coverage is 100%. Per guidelines, baseline is 4. The description adds no param info but none is needed.

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 returns connection status and URLs, explaining two scenarios. It does not explicitly differentiate from siblings like 'authenticate', but the purpose is very 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 implies usage for checking connection status but provides no explicit guidance on when to use versus alternatives like 'authenticate' or 'openfinance_provider_status'.

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 show readOnlyHint=false, but the description adds critical context: invoke works without installation, returns connect/checkout links for auth/payment, and writes require specific permissions. This goes well 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 long but every sentence adds value, structured to front-load purpose and flow. It could be slightly more organized (e.g., bullet points for actions), but it remains clear and efficient given the complexity.

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 complexity (15 params, no output schema), the description covers the essential flow, auth/payment edge cases, and parameter semantics for core actions. Some details (e.g., limit, cancel_reason) remain unexplained, but overall it is comprehensive.

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 compensates by explaining the roles of key parameters (action, mcp_id, tool_id, arguments) and the action enum values. However, some parameters (e.g., tier_slug, immediate, conversation) are not detailed, leaving gaps.

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 'THE official mcp.ai marketplace' and defines the core flow (search→describe→invoke/install). It distinguishes from sibling tools by positioning itself as the first tool to use for capability discovery, contrasting with external registries and other marketplace tools like list_tools, install, etc.

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

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

Explicitly states when to use: 'When the user wants a capability... use THIS tool FIRST'. Provides clear guidance on choosing between invoke vs install, and warns that writes require owner/admin. No ambiguity on usage.

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

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

Annotations already mark destructiveHint=true. The description adds value by specifying that consent is revoked, data is deleted, and a reconnection URL is returned, going beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences covering action, consequence, and return value, with no extraneous 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 simple tool with one parameter and no output schema, the description covers purpose, effect, and return value. It could mention that a connection must exist, but overall 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?

With 0% schema coverage for the single parameter 'item', the description provides no details on what 'item' represents or its format, leaving ambiguity for the agent.

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 revokes consent and deletes connection data for a specific bank, with a specific verb and resource. It distinguishes itself from siblings like openfinance_list_connections or openfinance_force_sync.

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 for disconnecting a bank but does not explicitly state when to use versus alternatives, nor does it provide exclusions or prerequisites.

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 discloses that the tool performs a PATCH then polls up to ~60s, waits by default, and can be fire-and-forget. It explains return fields including status, executionStatus, lastUpdatedAt, synced, needs_action, and timed_out. 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 well-structured with a clear first sentence stating the main action, followed by usage context, parameter details, and return value explanation. Every sentence provides essential information without 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?

Given no output schema, the description fully explains return values, error states (needs_action, timed_out), and next steps. It covers all critical aspects for a sync tool with polling, making it complete and actionable.

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?

Despite 0% schema description coverage, the description fully explains both parameters: 'items' as an array of selectors (with examples) and omission syncs all, and 'wait' as boolean with default behavior. This adds significant meaning beyond the raw 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 forces a bank to re-sync connections and waits for completion. It distinguishes itself from sibling tools like openfinance_get_item_status and openfinance_disconnect_bank by specifying that it pulls fresh data without disconnecting.

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 says use when a balance or transaction list looks stale, and provides alternatives: fire-and-forget with wait:false, and re-check with openfinance_get_item_status on timeout. It also explains when user action is needed (needs_action).

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?

Discloses detailed error behaviors beyond annotations: CREDIT accounts may return BALANCE_FETCH_ERROR with warning; upstream unavailability or non-Open Finance connectors degrade to last-synced balance with realtime: false and warning. 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?

Concise, front-loaded, every sentence adds value: endpoint, parameter constraints, error modes, response shape. No wasted words.

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

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

No output schema, but description gives response shape { results, errors } with details. Covers all necessary behavioral aspects for a read-only balance retrieval 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?

With 0% schema description coverage, description adds meaning: account_ids is array of strings, size 1-50. Provides more context than bare 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?

Clearly states it returns real-time balance per account id, including endpoint and specific parameter constraints. Distinguishes from sibling tools like openfinance_list_accounts or openfinance_get_accounts_detail.

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

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

Explicitly mentions pass account_ids as array 1-50 and describes error handling. Does not explicitly state when not to use, but context is clear. Lacks direct alternative 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 mark it as readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds important behavioral context: the batch response structure ({results, errors}), the possibility of a provider_incident block when the provider has an OPEN incident, and a critical warning that credit limits/balances may be unreliable in such cases. This goes well 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?

Three sentences: first sentence states core purpose and response shape, second sentence parameter requirement, third sentence a crucial behavioral warning. No extraneous words, front-loaded with the most important 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?

Given one parameter, no output schema, and strong annotations, the description covers all needed aspects: what the tool returns, how to use it (array size limit), and a critical edge case (provider incident). An agent has enough information to correctly invoke and interpret results.

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 has 0% description coverage for the only parameter `account_ids`. The description compensates fully by specifying it must be an array of strings with 1–50 items. This adds the cardinality constraint and batch usage context that the schema alone lacks.

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 states it returns full account objects with extended creditData per ID, batch shaped as {results, errors}. This clearly distinguishes it from siblings like openfinance_list_accounts (which returns a list without details) and openfinance_get_account_balance (balance only). The verb 'returns' + resource 'account objects' + scope 'per id' is specific and 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 says to pass `account_ids` as an array (1–50), providing concrete usage instruction. While it does not explicitly state when to use versus alternatives, the purpose is clear enough. It lacks explicit when-not-to-use guidance, but the context is sufficient for an agent to infer appropriate usage.

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

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

Annotations already mark the tool as read-only, idempotent, non-destructive. Description adds context that Pluggy does not return a paid/status field and explains the nuanced meaning of payments[] (reflects previous bill payments). 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?

Description is somewhat lengthy but well-organized: starts with what it returns, then what it doesn't, then usage instructions and caveats. Every sentence adds value. Slightly verbose but not wasteful.

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 no output schema, the description explains return fields (financeCharges, payments with subfields) and result shape ({ results, errors }). It covers important caveats (Pluggy status, payment interpretation) and references sibling tools. Completeness is high for the tool's complexity.

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

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

The schema has one parameter (bill_ids) with 0% description coverage. The description explains that bill_ids is an array of strings and advises to use openfinance_list_credit_card_bills first to discover IDs. It also mentions the batch shape. While it doesn't provide examples or constraints, it sufficiently clarifies the parameter's purpose.

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?

Clearly states that the tool returns bill-level detail for credit card bills by ID, listing fields like financeCharges and payments. Also explicitly distinguishes what it does not return (individual transactions), making 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 guidance: use openfinance_list_credit_card_bills first to discover IDs, use openfinance_list_transactions for itemized transactions, warns not to reconstruct totals from transactions, and directs to openfinance_list_credit_card_bills for paid status. Covers when to use and when to avoid.

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=true and destructiveHint=false, so the agent knows it's safe. The description goes beyond by specifying the returned data: status values, executionStatus, and connector metadata. It also reveals the response shape difference between bulk (count and items) and single (presumably the item object). No contradictions with annotations are present.

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 consists of two concise sentences. The first sentence captures the core purpose and example values, and the second explains parameter usage. Every word adds value with no redundancy or filler. It is front-loaded with the essential 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?

Given the tool's simplicity (one optional parameter, no output schema), the description covers the main usage scenarios and response keys. It does not detail error conditions or pagination for the bulk mode, but these are often beyond the minimal needed for correct invocation. With annotations providing safety guarantees, the description is sufficient for an agent to select and invoke the tool 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?

The schema has 0% description coverage for the single parameter 'item'. The description fully compensates by explaining that omitting 'item' returns status for all linked banks, while passing 'item' returns status for a single bank. This provides complete functional semantics, even though the exact format of 'item' (likely an identifier) is not specified.

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 returns the current status of a bank connection with enumerated examples (UPDATED, UPDATING, LOGIN_ERROR). It distinguishes between bulk (omit 'item') and single (pass 'item') modes, and specifies the return includes executionStatus and connector metadata. This clearly differentiates it from sibling tools like openfinance_list_connections, which likely list connections without detailed status.

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 guidance on when to omit vs. pass the 'item' parameter, covering both use cases. It implies that the tool should be used to get status rather than listing connections (handled by openfinance_list_connections). However, it does not explicitly state when not to use this tool or mention alternatives for other cases.

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. The description adds context about the GET endpoint, the batch processing with error handling, and the returned fields. No contradiction, and it enhances understanding of behavior 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?

The description is concise, single paragraph, but packs purpose, usage guidance, return fields, and parameter details. It front-loads the core purpose. Slightly verbose in listing fields, but still efficient.

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 (one parameter, no output schema), the description is complete. It lists the returned fields, usage sequence, and parameter constraints, providing sufficient information for an agent to select and invoke the tool correctly.

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

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

Schema has 0% description coverage, but the description adds meaning by stating the parameter is an array with a size constraint (1-50). This exceeds the schema's minimal definition and helps the agent correctly invoke the tool.

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 returns full loan contract detail by ID, lists key fields, and specifies the HTTP method and endpoint. It differentiates from sibling tool openfinance_list_loans by indicating its use for deep-diving into a specific contract.

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

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

Explicitly instructs to use after openfinance_list_loans to deep-dive on a specific contract. It also specifies the parameter constraints (array of 1-50 loan_ids) and the batch output shape. No explicit when-not-to-use guidance, but the context is 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?

Beyond annotations (readOnlyHint=true, idempotentHint=true), the description discloses that the response may include a 'provider_incident' block indicating unreliable data, and explains that credit balance meaning varies by connector. No contradictions 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 long but well-organized, starting with the main purpose then covering details about fields, usage patterns, warnings, and cross-references. While every sentence adds value, it could be slightly more concise without losing critical 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?

Given no output schema, the description compensates thoroughly by listing return fields (balance, number, type, subtype, bankData, creditData), explaining the 'bank' field and 'connector_id', and detailing the meaning and caveats of credit balance. It also covers provider incident behavior, making the tool fully understandable.

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 no descriptions (0% coverage), but the description fully explains both parameters: 'item' omitting aggregates all connections, passing targets a single bank; 'type' enum values (BANK, CREDIT) are defined. This adds all necessary semantics beyond 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 returns accounts for a bank connection with specific fields (balance, number, type, etc.) and distinguishes between BANK and CREDIT types. It also differentiates from sibling tools like openfinance_list_credit_card_bills by directing users to that tool for standardized bill data.

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 guidance on when to omit the 'item' parameter (to list all accounts across banks) and when to pass it (for a single bank). It warns about the connector-dependent meaning of credit balance and advises against treating it as the current bill. It also references the sibling tool for standardized bill amounts.

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 idempotentHint=true. The description adds valuable behavioral context: the data is cached for the adapter session and is a single aggregated response with no batch ids. 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?

Three sentences, no redundant words. Front-loaded with main purpose, then key details. Efficient and clear.

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 no parameters and no output schema, the description fully covers the tool's behavior and return fields. It explains caching, structure, and related tool usage. Complete for its simplicity.

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

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

No parameters exist, so baseline is 4 per rules. The description does not need to add parameter information.

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 returns Pluggy's transaction category taxonomy, cached for the adapter session. It specifies the exact fields returned (id, description, descriptionTranslated, parentId, parentDescription) and notes it's a single aggregated response. No sibling tool duplicates this 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?

The description explains that the 'id' is used by openfinance_update_transaction_category and that descriptionTranslated is preferred for pt-BR users. This implies context but lacks explicit when not to use it, though no alternatives exist.

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=true, idempotentHint=true, and destructiveHint=false, so the description adds value by specifying the returned fields and the add_connection_url. No contradictions, but no additional behavioral 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, focused sentence that covers the purpose and output without extraneous information. Every word contributes meaning.

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 lists the return fields, which compensates for the lack of an output schema. However, it does not mention pagination or whether the list is limited. Given the simplicity of the tool (list all connections), it is reasonably 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?

With zero parameters and 100% schema coverage, the description does not need to add parameter details. It correctly focuses on output fields, which is appropriate given the lack of 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 clearly states the verb 'Returns' and the resource 'saved bank connections' and lists the specific fields returned (connector_id, item_id, bank name, add_connection_url). It distinguishes from sibling tools that list accounts or 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 implies usage for viewing saved connections and obtaining the add_connection_url for linking more banks, but it does not explicitly state when to use this tool versus alternatives (e.g., list_accounts or list_transactions). No exclusion criteria or alternative tool mentions.

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?

Discloses numerous behavioral traits beyond annotations: payment_status derivation algorithm, cross-bill payment transfer logic, connector asymmetry for open bills, and bill_grouping_reliability warnings. Annotations confirm readOnlyHint and idempotentHint, and the description adds rich context about data semantics.

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 very long and dense, but it uses headings (IMPORTANT, CONNECTOR ASYMMETRY) and logical flow. It contains many necessary details, but could be more concise. It is structured but not optimally 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 complexity (5 parameters, no output schema, many edge cases), the description is exceptionally thorough. It covers return fields, payment logic, connector asymmetries, warnings, and relationships to other tools. It provides all necessary context for correct 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?

Schema description coverage is 0%, so the description must compensate. It explains include_open_bill and account_ids partially (bulk support), but does not describe page, page_size, or account_id explicitly. The main account_id parameter is implied but not clearly documented in 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 clearly states the tool returns CLOSED credit card bills for a CREDIT-type account, listing specific fields like dueDate, totalAmount, payment_status, etc. It distinguishes itself from related tools like openfinance_list_transactions by specifying this is bill-level summaries, not individual 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?

Provides explicit when-to-use guidance including payment_status logic, cross-bill payment handling, and connector asymmetries for open bills. It advises when to use openfinance_list_transactions for itemized purchases and not to sum transactions by billId. It also warns about cross-bank attribution.

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 annotations (readOnlyHint, idempotentHint), the description adds error handling behavior (returns warning instead of throwing) and lists returned fields. No contradictions 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 a single, well-structured sentence that front-loads the primary purpose, then efficiently lists asset types, fields, and error behavior. No redundant or irrelevant 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?

Given 4 parameters, no output schema, and many siblings, the description is adequate but incomplete. It covers purpose and error handling, but lacks parameter documentation and pagination details, leaving gaps for agent understanding.

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 implicitly links 'item' to connection and lists asset types that map to the 'type' enum, but does not explicitly explain page or page_size parameters. Partial compensation but insufficient for full clarity.

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 returns investment portfolios for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.). It distinguishes itself from sibling tools like openfinance_list_investment_transactions by focusing on portfolio snapshot versus 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 implies usage for connections with INVESTMENTS enabled and describes fallback behavior, but does not explicitly compare to alternatives or state when not to use this tool. Implied but lacks explicit 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, destructiveHint, so safety profile is covered. The description adds value by detailing the return fields (quantity, value, amount, netAmount, expenses) and transaction types, enhancing transparency 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?

The description is concise with two paragraphs: first explaining purpose and output fields, second mentioning bulk support. It avoids fluff but could be more structured (e.g., separating output details from usage notes).

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 no output schema, the description adequately explains the output structure (fields like quantity, netAmount, expenses) and transaction types. It also provides prerequisite context (use after list_investments). Missing pagination parameter documentation slightly reduces 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?

Schema coverage is 0%, so description must compensate. It explains investment_id (required) and investment_ids for bulk, but omits pagination parameters (page, page_size). Partial coverage leaves some parameters unexplained, resulting in a moderate score.

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 returns 'movement history for a specific investment position' with enumerated transaction types (BUY, SELL, TAX, etc.) and detailed field names. This distinguishes it from siblings like openfinance_list_investments which lists investments themselves.

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

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

Explicitly instructs to 'use after openfinance_list_investments to get the investment_id', providing a clear prerequisite. Also mentions bulk support via investment_ids, helping the agent decide when to use this tool over alternatives.

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=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral details: sequential querying with rate-limit spacing and the return structure {results, errors} per connection. 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 two sentences, front-loaded with purpose and endpoint, then parameter usage and behavior. Every sentence adds value with no wasted words.

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 one optional parameter, no output schema, and annotations covering safety, the description explains input and output sufficiently. It mentions errors per connection but lacks detail on error handling. Still, it's largely complete for the tool's complexity.

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

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

The input schema has one parameter 'items' as an array of strings with 0% coverage. The description explains that items are connection selectors (item_id uuid, connector_id, or connector_name), and the behavior when omitted. This adds critical meaning beyond 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 it lists loan contracts per bank connection, specifies the HTTP endpoint GET /loans, and distinguishes between providing items for specific connections or omitting for all linked banks. This differentiates it from sibling tools like openfinance_list_accounts or openfinance_list_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 explicitly explains when to pass items (for specific connections) and when to omit items (for all banks). It also mentions sequential querying with rate-limit spacing. While it doesn't explicitly list when not to use it, the context is clear and provides good 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 description adds rich behavioral context beyond annotations: auto-pagination with truncation at 5000, error returns without throwing, account echo block, provider_incident block, detail levels, and connector-specific behavior for credit cards. No contradiction with annotations (readOnlyHint, idempotentHint).

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 very long but well-structured. Every sentence adds value, and key points are front-loaded. However, the length might be slightly excessive for an LLM to parse quickly; a more compact version could improve conciseness. Still, it's appropriate for the tool's complexity.

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 is exceptionally thorough, covering error handling, pagination, detail levels, edge cases (sparse billId, connector variance), provider incidents, and account identification. It is fully complete for a tool with 8 parameters and no output schema.

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

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

With 0% schema description coverage, the description compensates fully. It explains all parameters: from/to (ISO dates), page, page_size, detail (and its enum values), account_id, account_ids (bulk), and search_queries (case-insensitive substring, OR semantics, aggregation limit). This adds significant meaning beyond the bare 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 returns transactions for bank accounts of type BANK or CREDIT, and explicitly distinguishes itself from openfinance_list_credit_card_bills for credit card bills. The verb 'returns' and resource 'transactions' are specific, and the tool's unique role for credit card itemized transactions is highlighted.

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 extensive guidance: when to use this tool (to get itemized credit card transactions), when not to (for bill totals, use openfinance_list_credit_card_bills), and alternatives (openfinance_get_item_status for sync issues). It also advises on pagination, search_queries usage, and mention of provider incidents.

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. The description adds critical behavioral details: a scan cap of 5000/account with truncated:true flag, a provider_incident block warning of potential incompleteness due to provider outages, and default behavior of returning a compact summary. This far exceeds the information from annotations alone.

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 each sentence adds unique value, starting with the core purpose and differentiation. Parameter explanations are logically ordered. While dense, it avoids redundancy; however, it could be slightly more concise by grouping some details.

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

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

No output schema, so the description thoroughly explains return values: compact summary fields (total entradas, saídas, etc.), monthly evolution, top expenses/incomes, per-account breakdown, and for raw granularity, consolidated transactions with enrichment options. It also covers truncation and provider_incident blocks, making the tool's full behavior clear.

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 fully compensates by explaining every parameter: 'item' (connector_id, connector_name, or omit for all), 'from'/'to' (ISO dates), 'granularity' (monthly vs raw with distinct outputs), 'detail' (compact, rich, raw with enrichment details), 'type' (BANK/CREDIT), and implies 'top_n' controls size of top lists. All semantic meaning is provided.

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 states it performs consolidated cash-flow analysis for a whole bank connection in one call, resolving accounts internally and fanning out transactions. It clearly distinguishes from sibling tools like openfinance_list_accounts and openfinance_list_transactions by noting you do not need to call them first. The purpose is specific and actionable.

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 when-to-use guidance ('análise anual/mensal', 'fluxo de caixa', etc.) and explains when to use alternatives like granularity:'raw' for itemized rows. It also covers omitting the 'item' parameter to analyze all linked banks, giving clear context for different use cases.

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. Description adds context about it being a live public status page check and details return fields (global indicator, degraded components, open incidents, your_banks_affected). 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?

Description is a single dense paragraph that efficiently conveys purpose, usage, and return value. Every sentence adds value, no wasted words.

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 tool with good annotations, the description is complete: it explains the purpose, when to use, what it returns (without output schema). No gaps.

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

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

Tool has 0 parameters, so schema coverage is 100%. Description adds no parameter info but correctly implies no input needed. Baseline 4 for zero 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?

Description clearly states it checks the LIVE operational status of the Open Finance provider's public status page, distinguishing it from the user's connection status (openfinance_get_item_status). It provides specific use cases and sibling differentiation.

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

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

Explicitly describes when to use: when data looks incomplete or stale despite an UPDATED connection, indicating an upstream outage or incident. Clearly contrasts with openfinance_get_item_status.

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 read-only, idempotent, non-destructive behavior. Description adds that it honors user's plan, returns caveat warnings for credential connectors, and never dumps the whole catalog. These details go 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?

The description is thorough but not overly verbose. It front-loads the main purpose, then adds critical details like caveats and plan filtering. A minor trim could improve conciseness, but every sentence 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?

Given the tool's complexity (returns multiple fields, caveats, plan constraints, no output schema), the description covers all necessary behavioral and output information. It ensures an agent can correctly invoke and interpret results.

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%, but the description fully explains both parameters: keywords[] with example usage ('nubank','btg') and include_accounts for returning accounts. No schema descriptions exist, so the description compensates completely.

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 searches bank connectors by name, listing returned fields (connector id, access type, audience, linked connections, connect_url). It distinguishes from siblings like authenticate, connect, and marketplace by specifying its role as a pre-connection lookup.

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

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

Explicitly instructs to call this before connecting, notes keywords[] is required, warns against dumping the catalog, and explains how plan filtering works. Provides clear when-to-use and 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), description reveals side effect: overriding automatic categorization AND teaching Pluggy by creating Category Rules. Also describes batch error handling and output shape. Provides comprehensive behavioral context.

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 that front-load purpose, then detail input, side effect, and output. Efficient and well-structured, though slightly dense. Every sentence 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?

Covers purpose, input format, side effect (rule creation), and output shape. Without an output schema, the description adequately documents response structure. No gaps for complexity level.

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?

Despite 0% schema coverage, description fully explains the 'items' parameter: an array of objects with transaction_id and category_id, including where to get these IDs. Adds critical meaning beyond the plain 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?

Description clearly states the tool corrects transaction categories via PATCH endpoint, specifies input format (items array with transaction_id and category_id), and references sibling tools for ID sources. Distinguishes itself from listing 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?

Explicitly says 'use this to fix miscategorized transactions and improve categorization accuracy going forward.' Provides context for when to use but does not explicitly state when not to use or list alternatives. However, the guidance is clear and actionable.

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 indicate idempotentHint: true and destructiveHint: false), the description adds no behavioral context. It does not disclose side effects, authorization needs, rate limits, or what happens upon submission. The mention of conversation array is a parameter hint, not behavioral.

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, concise and front-loaded with the core action. Every word serves a purpose, with no filler or 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?

Given the tool has 3 parameters and no output schema, the description is incomplete. It does not cover the context parameter, expected format of message, or any return values. An agent would lack sufficient information to use the tool reliably.

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 compensate. It adds meaning to the conversation parameter (should be an array with recent messages) but does not explain context or message. This partial addition provides some value but leaves gaps.

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 uses specific verbs and resources, distinguishing it from sibling tools that focus on OpenFinance operations and authentication.

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 no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or contextual cues for choosing this tool over others.

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. The description adds value by specifying that it returns 'platform and adapter versions', providing additional 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 sentence that is perfectly front-loaded and concise. Every word is meaningful and earns its place.

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

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

Given that there are no parameters and no output schema, the description fully covers what the tool does. It is complete for a simple version retrieval 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 no parameters, and schema coverage is 100%. The description does not need to elaborate on parameters. A score of 4 is appropriate as the baseline for zero-parameter tools.

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 shows current MCP platform and adapter versions. It uses a specific verb and resource, and given the sibling tools (authentication, finance operations, etc.), it stands out as a version information 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 that the tool should be used when version information is needed. There are no explicit when-not or alternatives, but due to its simplicity and zero parameters, the usage context is 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?

The description fully discloses what the tool returns, and annotations already confirm it's read-only and idempotent. There are no contradictions, and the description adds specific behavioral context about the output components.

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 efficiently conveys the tool's purpose. It is concise without being vague.

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 no parameters and no output schema, the description completely explains what the tool returns and its purpose. There are no gaps for an agent to interpret.

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, so the baseline is 4. The description does not need to add parameter information, and it appropriately focuses on the output.

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 what the tool does: it returns the toolkit state including installed MCPs, their connection status, and how many catalog tools each exposes. This distinguishes it from siblings like 'authenticate' or 'connect' which serve different purposes.

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?

While the description doesn't explicitly say when to use this tool over alternatives, its read-only nature and lack of parameters imply use for informational queries. Given no similar tools exist among siblings, the context is clear enough.

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