Safra MCP

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

Discloses that calling with a token grants session-only access, while adding token to config yields permanent connection. This adds context beyond the idempotentHint annotation, though it doesn't detail failure modes or side effects.

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

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

Two sentences cover the entire functionality, audience, authentication methods, and invocation. No wasted words; efficient and front-loaded.

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

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

The description is fairly complete for an authentication tool without an output schema. It explains both modes and how to call. It could mention what the returned link looks like, but that's minor.

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 single optional parameter 'token' is fully explained: it's the JWT token to paste for session login, and omitting it returns a login link. This compensates for the 0% schema coverage.

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 is for authentication of IDE agents like Cursor. It specifies two distinct methods (permanent config vs session-only) and distinguishes itself from sibling tools like 'connect' by focusing on token-based login.

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 on when to use the config approach versus pasting a token, and how to invoke the tool with or without arguments. It lacks a direct comparison to siblings but gives clear usage scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, indicating a safe read operation. The description adds value by detailing the two possible return states (authenticated vs credentials missing), providing behavioral context beyond what annotations offer.

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 long, front-loads the purpose, and contains no unnecessary words. Every sentence adds information about the output states.

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 no parameters and no output schema, the description sufficiently explains the return values (authenticated field, pending array, connect_url) and the conditions under which they appear. It covers the essential behavior completely.

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% trivially. Per the scoring rule, baseline is 4. No additional parameter explanation 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 it returns connection status and URLs, and distinguishes the two states (authenticated vs missing credentials). It is specific about the resource and verb, and differentiates from sibling tools like 'authenticate' which performs an action rather than a status check.

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 (to check connection status) but does not explicitly compare to alternatives or state when not to use. It lacks direct guidance on sibling differentiation, relying on context.

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 thoroughly discloses behavior beyond annotations: that invoke runs MCPs even when not installed without bloating the toolkit, that it returns connect/checkout links for missing credentials or payment, and that writes require owner/admin. This adds significant context to the annotations (readOnlyHint=false, destructiveHint=false) without 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 verbose paragraph combining all guidance. While it front-loads purpose and core flow, the density of information makes it hard to parse quickly. It could be more structured (e.g., bullet points for actions or parameters) to improve scannability.

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 (15 parameters, multiple actions, no output schema), the description covers the high-level workflow exhaustively—search, describe, invoke, install, etc.—and handles edge cases like credential/payment flows. However, it lacks parameter-level details and does not describe return values, leaving some gaps for a fully informed 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?

With 15 parameters and 0% schema description coverage, the description only implicitly covers a few (action, mcp_id, tool_id, arguments) through the flow narrative. Many parameters (limit, query, immediate, tier_slug, conversation, request_name, cancel_reason, etc.) remain unexplained, leaving the agent to guess their purpose and format.

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 is 'THE official mcp.ai marketplace' and specifies its role as the in-platform catalog and execution engine. It distinguishes itself from external registries with phrases like 'use THIS tool FIRST, before any external/generic registry.' The core flow (search→describe→invoke) is explicitly outlined.

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 use the tool ('When the user wants a capability... use THIS tool FIRST') and when to prefer alternatives (e.g., 'prefer invoke for a single/occasional use' vs. 'install only to make an MCP PERMANENT'). It also details prerequisites for writes ('require workspace owner/admin') and error handling for credentials or payment.

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 destructiveHint=true and description confirms deletion and data unavailability. It adds the behavioral detail that a reconnection URL is returned, which goes beyond the annotation hint. 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 concise (three sentences) and front-loaded with the main action. However, the lack of parameter explanation is a significant omission that reduces effectiveness despite brevity.

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 destructive tool with one parameter and no output schema, the description covers the core effect and reconnection behavior. However, it lacks error conditions, prerequisites (e.g., must be connected), and a detailed return value structure.

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 single required parameter 'item' is not described at all in the description, despite 0% schema coverage. The phrase 'for a specific bank' implies it identifies the bank, but the description does not explicitly define or hint at the expected value format or meaning.

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 ('Revokes... consent and deletes... connection data') and identifies the resource (a specific bank). This distinguishes it 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 explains the consequence ('data no longer available') and the reconnection option (returns an add_connection_url), providing clear context for use. However, it does not explicitly state when not to use it or contrast with 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 provide readOnlyHint=false, but description adds blocking behavior (~60s poll), no disconnect/reconnect, return fields like status, executionStatus, needs_action, timed_out. 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?

Well-structured and front-loaded, but moderately long (3 sentences). Every sentence adds value, yet slightly verbose.

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, description fully explains return structure (results, errors, status, synced, timed_out, needs_action) and actions to take. Covers all essential context.

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%, but description compensates by explaining `items` array (selectors, omit for all) and `wait` boolean (fire-and-forget). Adds meaning beyond 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 re-sync and waits, distinguishing it from sibling tools like openfinance_get_item_status. It specifies the verb 'force sync' and the resource 'one or more connections'.

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 tells when to use ('balance or transaction list looks stale'), what it does without disconnecting, and mentions alternatives (re-check with openfinance_get_item_status, fire-and-forget option).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds real-time nature, structured error handling, and response shape, providing full 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?

Three sentences with essential information (endpoint, parameter details, error behavior, response shape). No superfluous words, but slightly dense.

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

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

With no output schema, the description provides response shape. Parameter fully documented. Error handling explained. Annotations cover safety. Fully complete given complexity.

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

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

Schema coverage is 0%, but the description fully compensates by explaining the 'account_ids' parameter is an array with size limit 1-50 and its purpose. No ambiguity.

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 'real-time balance payload per account id' and specifies the endpoint. It distinguishes from sibling tools like 'openfinance_get_accounts_detail' by focusing on balance retrieval.

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 parameter requirements (array of 1-50 account_ids) and special behavior for CREDIT accounts (BALANCE_FETCH_ERROR with warning). It does not explicitly contrast with alternatives, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safety. The description adds significant value by disclosing the batch processing behavior ({ results, errors } shape) and crucially warning about provider_incident blocks where credit limits/balances may be unreliable. This proactive disclosure 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?

The description is concise (3 sentences), front-loads the core purpose, then provides essential behavioral context. Every sentence adds value with no 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?

Given the tool has 1 required param, no output schema, and moderate complexity (batch processing, potential unreliable data), the description covers the response shape, limitations, and data reliability caveat. It lacks explicit output fields but the mention of 'full account objects including extended creditData' provides adequate context.

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 bears full responsibility. It explains that account_ids is an array (1-50) of IDs, matching the GET /accounts/:id endpoint. This adds meaning beyond the raw schema (array of strings). It does not specify the exact format of IDs but is sufficient for 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 it returns full account objects with extended creditData per ID using GET /accounts/:id. It specifies the batch size limitation (1-50). However, it does not explicitly differentiate from sibling tools like openfinance_list_accounts (list all accounts) or openfinance_get_account_balance (balance only), which would help the agent decide when to use this 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 explains how to use the tool (pass account_ids as an array 1-50) and describes the batch response shape. It does not provide guidance on when to use this tool versus alternatives, nor does it mention prerequisites or context for choosing it over other openfinance 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?

Discloses important behavioral traits beyond annotations: Pluggy does not return a paid/status field, explains the meaning of payments[] in Brazilian Open Finance (payment of previous bill), warns about sparse billId in transactions, and describes the batch shape. 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 fairly long but well-structured with front-loaded main purpose, followed by exceptions and usage details. Every sentence adds value, though some trimming could improve 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?

Given the complexity of credit card bill data and missing output schema, the description covers critical edge cases (paid status, payments semantics, batch errors). It lacks a full list of return fields but addresses core concerns.

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 description compensates by explaining that bill_ids is an array of IDs discovered via another tool. It does not provide additional constraints or examples but sufficient for correct 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 it returns bill-level detail for credit card bills by id, explicitly lists included fields (financeCharges, payments with subfields), and distinguishes itself from the transaction-listing tool by stating what it does NOT return.

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 step-by-step guidance: first use openfinance_list_credit_card_bills to discover ids, pass bill_ids as an array, warns against reconstructing totals from transactions, and explains when to use the sibling tool openfinance_list_transactions for itemized data.

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 confirm readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds value by detailing the returned data (status enum, executionStatus, metadata) and the conditional output structures. 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?

Two sentences: first states purpose and return fields, second describes conditional parameter usage and output shape. No redundant information; front-loaded and 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 no output schema and two distinct use cases, the description provides enough detail for tool selection and invocation: it specifies the return shape for the all-banks case and hints at fields for single bank. However, a more complete description of the single bank output would enhance precision.

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 effectively compensates by explaining the optional 'item' parameter: omit for all banks or pass a string for a single bank. It clarifies the different outputs but does not specify that 'item' is likely a connection ID. The schema already indicates type string, so the meaning is 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 the tool returns the current status of a bank connection with specific enum values (UPDATED, UPDATING, LOGIN_ERROR, etc.), executionStatus, and connector metadata. It differentiates behavior based on the 'item' parameter: omit for all linked banks or pass for a single bank. This is a specific verb+resource and distinguishes from siblings like openfinance_list_connections.

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 guides when to omit or provide the 'item' parameter and hints at the output shape for the all-banks case. It provides clear context for usage but does not explicitly mention when not to use it or compare with sibling tools like openfinance_list_connections 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 already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds additional behavioral context: it mentions the batch response shape '{ results, errors }' and the array size constraint (1-50). While useful, the description does not significantly extend beyond what annotations imply.

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 a list of returned fields. It is front-loaded with the purpose and usage recommendation. While the field enumeration makes it somewhat lengthy, every part serves to inform the agent. It is well-structured and not excessively verbose.

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 one parameter, no output schema, and annotations present, the description covers the purpose, usage context, parameter constraint, and response shape. It lacks explicit error handling or authentication details, but these are not critical for a read-only, idempotent tool with clear usage instructions.

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 by specifying that loan_ids should be an array of loan IDs with a size limit of 1-50, and describes the batch response structure. This provides essential clarity beyond the bare schema definition.

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, listing specific fields such as interestRates, warranties, installments schedule, etc. It also distinguishes itself from sibling tools by recommending usage after openfinance_list_loans 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?

The description explicitly says 'Use after openfinance_list_loans to deep-dive on a specific contract,' providing clear context. It also specifies that loan_ids should be an array of 1-50 items. However, it does not explicitly state when not to use this tool or mention alternative tools, slightly reducing the score.

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=true, idempotentHint=true, destructiveHint=false. Description adds critical context: `balance` is connector-dependent, `bank` vs `name` distinction, `provider_incident` block causing unreliable values, billing cycle 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?

Well-structured with front-loaded purpose. Each sentence adds value, but length is high. Could be slightly tighter, but no redundancy.

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

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

Given no output schema, description covers return fields, special cases (connector-dependent balance, provider incidents), and cross-references sibling tools. Complete for tool complexity.

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

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

Schema has 0% description coverage. Description fully compensates: explains `item` targets a single bank and omitting lists all, explains `type` enum values (BANK/CREDIT). Adds meaning beyond 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 it returns accounts (BANK/CREDIT) with specific data fields. It distinguishes from sibling tools like openfinance_list_credit_card_bills and openfinance_get_accounts_detail by mentioning alternative tool for standardized bill amounts.

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 when to omit `item` (all banks) vs pass `item` (single bank). Warns not to treat `balance` as bill and refers to openfinance_list_credit_card_bills for standardized amounts. 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds caching behavior ('cached for the adapter session') and explains it's a single aggregated response, providing useful 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 two sentences, no wasted words. First sentence front-loads the main purpose. Every sentence adds value, including the note about single response and lack of batch ids.

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 the return structure and caching. It also relates to a sibling tool (update). For a parameterless list tool with good annotations, it is complete and 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?

No parameters in schema (100% coverage by default), so baseline is 4. Description adds meaning by detailing the return fields (id, description, descriptionTranslated, parentId, parentDescription) and their usage, which compensates for the lack of output 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 returns Pluggy's transaction category taxonomy, cached, with fields explained. It distinguishes from siblings by noting it's a single aggregated response without batch ids. The title from annotations reinforces the 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 implies usage context by noting the 'id' is used by 'openfinance_update_transaction_category', but does not explicitly state when to use this tool versus alternatives or when not to use it. No explicit when/when-not 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 indicate readOnlyHint, idempotentHint, destructiveHint (safe, idempotent read). The description adds valuable behavioral context: it returns specific fields and includes an add_connection_url for linking additional banks, going 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, well-structured sentence that front-loads the purpose and lists key outputs. Every part is necessary; 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 zero parameters, no output schema, and annotations already covering safety/idempotency, the description fully explains what the tool returns (fields and add_connection_url). It is complete for a simple list 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?

No parameters (0), so schema coverage is 100%. The description adds no parameter information, but with no parameters to document, the baseline of 4 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 uses the specific verb 'Returns' and resource 'saved bank connections', listing exact fields like connector_id, item_id, bank name, and add_connection_url. It clearly distinguishes from sibling list tools (e.g., openfinance_list_accounts, openfinance_list_transactions) by focusing on connections.

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

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

The description implies the tool is for listing bank connections but does not explicitly state when to use it over alternatives or provide exclusions. Context signals show no required parameters, making it straightforward, but lack of 'when not to use' guidance keeps this at a 3.

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 (readOnly, idempotent, nondestructive), the description discloses key behaviors like derived payment_status, lack of paid field, cycle logic, connector asymmetry, and warning on missing products.

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, covering many nuances. While it starts with the core purpose, it could be more concise and structured for quick consumption. The wall of text may overwhelm the agent.

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 and lack of output schema, the description comprehensively covers return values, edge cases, payment status logic, connector asymmetry, and error conditions, making it fully self-contained.

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, the description explains include_open_bill (default false, opt-in) and account_ids (bulk). However, page and page_size parameters are not described, though their purpose is inferable from standard pagination.

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 and distinguishing from sibling tools like openfinance_list_transactions and openfinance_get_credit_card_bill.

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 on when to use, including opt-in for open bill, connector asymmetry, and warnings against using for individual transactions or summing by billId. It also mentions alternatives like openfinance_list_transactions for itemized data.

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 idempotentHint=true. The description adds valuable behavioral context: it returns a structured error object { total:0, results:[], warning } instead of throwing on 403 or other errors, and details the fields in each row (balance, amount, rates, etc.). This goes 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 packs significant detail about asset types, return fields, and error handling. It is concise but could be structured into multiple sentences for improved readability. No unnecessary 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?

The description explains the return structure and fields well, but fails to document the input parameters (item, page, type, page_size). Given the tool lists investments with pagination, the lack of parameter documentation leaves the agent guessing. The description is adequate for basic understanding but incomplete for proper 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?

The schema has 4 parameters with 0% description coverage. The description does not explain any parameter's purpose or behavior. For example, 'type' is an enum but its effect on filtering is not mentioned. The agent must infer parameter semantics from the tool name alone, which is insufficient.

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 investment portfolio for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.). It distinguishes from sibling tools like openfinance_list_accounts by focusing on investments, and specifies the prerequisite (connection with INVESTMENTS product enabled).

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

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

The description implies this tool is for investment data, but does not explicitly state when to use it versus alternatives like openfinance_list_accounts or openfinance_list_transactions. No direct guidance on when not to use it or what prerequisites are needed beyond the implicit product enablement.

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 response fields (quantity, value, expenses breakdown) and bulk support, which go beyond the annotations without 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?

Two sentences with no fluff. First sentence defines core purpose and data; second sentence adds bulk support. Every word 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 no output schema and annotations covering safety, the description provides key purpose, return fields, prerequisite, and bulk option. Missing pagination details but overall sufficient for a list tool.

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

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

Schema has 0% description coverage. The description explains investment_id and investment_ids for bulk execution but omits page and page_size, which are left unexplained. Partial compensation for low coverage.

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 the tool returns movement history for a specific investment position, listing transaction types (BUY, SELL, etc.) and specific fields. Distinguishes itself from sibling tools by referencing openfinance_list_investments as a prerequisite.

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 after openfinance_list_investments to get the investment_id,' providing clear context. While it doesn't explicitly exclude other cases, the prerequisite and sibling tool list imply when this tool is appropriate.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) already indicate safety. The description adds value by disclosing sequential querying with rate-limit spacing and the return format ({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?

Three sentences pack all essential information: action, parameter usage, return format. No wasted words. Front-loaded with the main 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 the single parameter and no output schema, the description covers usage modes, rate-limiting behavior, and return structure. It is fully adequate 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?

With 0% schema description coverage, the description fully explains the `items` parameter: it's an array of connection selectors (item_id uuid, connector_id, or connector_name), and omitting it fetches all connections. This adds crucial meaning.

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 ('Lists') and resource ('loan contracts per bank connection') and clearly identifies the action (GET /loans). It distinguishes from sibling tools like list_accounts or list_transactions by focusing on loans.

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 guidance on when to pass `items` (for specific connections) vs omit (for all banks), and mentions rate-limit spacing. Lacks explicit comparison to sibling tools, but the context makes it clear this is for loans.

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

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

Adds extensive behavioral context beyond annotations: auto-pagination up to 5000 with truncation, upstream error handling returning structured error objects, credit card billId being a per-connector hint, variation in status/coverage across connectors, search_queries semantics, and provider_incident block. 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?

Long but well-structured: front-loaded with main purpose, then usage details, pagination, error handling, parameter explanations, and edge cases. Some repetition (credit card metadata hints mentioned twice) and minor verbosity, but every sentence adds value. Could be slightly more 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 complexity (8 parameters, no output schema), the description is remarkably complete: explains return behavior (truncation, error format), all parameter behaviors, relationships with other tools (bills, item status, force sync), and troubleshooting steps for zero results. Thoroughly covers edge cases like provider incidents and connector-specific behavior.

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

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

With 0% schema description coverage, the description compensates fully by explaining every parameter: from/to (ISO YYYY-MM-DD), page (omit vs explicit), page_size, detail (compact/rich/raw with recommendations), search_queries (case- and accent-insensitive substring, OR logic, 5000 limit), account_id/account_ids (bulk support). Provides meaningful semantics beyond 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 (BANK or CREDIT type), with specific verb 'returns' and resource 'transactions'. It distinguishes from sibling tools like openfinance_list_credit_card_bills by noting this is the only way for itemized credit card transactions, and also differentiates from openfinance_list_transactions_by_item.

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 on when to use this tool vs alternatives (e.g., use openfinance_list_credit_card_bills for standardized bill totals), when to apply date filters, search_queries, pagination modes, and when to check connection health via openfinance_get_item_status if total is 0. Covers provider incidents and bulk support.

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 read-only and idempotent, but the description adds critical details: truncation at 5000/account (with truncated flag), provider_incident block affecting data completeness, and default compact output behavior.

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?

Well-structured with front-loaded purpose, then detailed parameter explanations. Slightly long but every sentence adds value; minor redundancy could be trimmed.

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 all 7 parameters, default outputs (compact summary fields), edge cases (truncation, provider incidents), and usage alternatives. No output schema, but description sufficiently explains return structure.

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 thoroughly explains each parameter: ISO date format for to/from, item types, type filtering, top_n for top expenses, detail values (compact/rich/raw), and granularity (monthly/raw). Fully compensates for schema gap.

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

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

The description clearly states the tool provides consolidated cash-flow analysis for a whole bank connection in one call, resolving accounts internally. It distinguishes from sibling tools like openfinance_list_transactions and openfinance_list_accounts by eliminating the need for multiple calls.

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 tells when to use it (analysis, cash flow, etc.), when not to call openfinance_list_accounts first, and how to use parameters (omit item for all banks, use raw granularity for itemized rows). Includes alternative actions for 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, destructiveHint. Description adds that it is a live check against a public status page, and details the return structure (global indicator, degraded components, incidents, affected banks). 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?

Front-loaded with the core action in the first sentence. Every sentence adds value: usage guidance, return details, and connection to user's banks. No fluff; concise yet comprehensive.

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 no output schema, the description fully describes the return information (global indicator, degraded components, open incidents, your_banks_affected). Covers all context needed for a zero-parameter 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?

No parameters exist; schema coverage is 100% (empty). The description adds no param info as none needed, meeting the baseline of 4 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 it checks the LIVE operational status of the Open Finance provider's public status page, using specific verb 'Checks' and resource 'provider status'. It distinguishes from sibling tool openfinance_get_item_status by contrasting provider health vs connection 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?

Explicitly advises when to use: when data looks incomplete or stale even though a connection shows UPDATED, and clarifies it helps differentiate a provider-side problem from a connection issue. Names specific alternative (openfinance_get_item_status) for the other case.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds context: it returns a hint when keywords are missing, honors user's plan (PF hides PJ), and surfaces caveat warnings for credential connectors. 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 detailed but well-structured, front-loading the purpose. Could be slightly trimmed, but each sentence adds value. No redundancy.

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

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

Given the tool's search role and annotations, the description is comprehensive: explains output fields, caveats, plan behavior, and usage context. No output schema, so description adequately covers return values.

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 explain parameters. It describes keywords as an array of bank names with examples, and mentions include_accounts for including accounts. It adds practical 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 the tool searches bank connectors by name, specifies input (keywords array) and output fields (connector id, access type, audience, linked connections, connect_url). It distinguishes from siblings by advising to call before connect and noting it doesn't dump the entire catalog.

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 states when to use the tool ('Call this BEFORE connecting') and provides guidance on interpreting caveats for non-Open-Finance connectors. It also notes that keywords is required, though the schema doesn't mark it as required, causing slight 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?

Beyond annotations, the description explains significant side effects: overriding Pluggy's categorization and creating a Category Rule that affects future transactions. Also details batch return structure and error isolation.

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

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

Every sentence adds value, front-loaded with purpose, efficient in conveying complex behavior and return format 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?

Complete for a mutation tool: explains side effects, return shape, error handling, and dependencies, despite 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?

Despite 0% schema description coverage, the description fully explains the `items` parameter structure, including required fields and where to derive values from other 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 the tool corrects the category of one or more transactions, specifying the HTTP method and distinguishing it from sibling list tools by referencing where input IDs come from.

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 tells when to use (fix miscategorized transactions) and provides sources for required IDs (openfinance_list_transactions, openfinance_list_categories), plus describes batch error handling.

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 idempotentHint (true) and destructiveHint (false). The description adds useful behavioral context by specifying that the conversation array should be included for reproduction. However, it does not disclose what happens after submission (e.g., storage, forwarding).

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 extremely concise, using two sentences to deliver purpose and usage guidance without extraneous words. 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?

Given no output schema and limited parameter descriptions, the description provides only minimal completeness. It explains the key input (conversation) but omits details on the tool's internal behavior or response. For a simple reporting tool, it is adequate but not rich.

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

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

With 0% schema description coverage, the description must compensate. It explains the 'conversation' parameter well but does not describe the 'context' parameter or provide details beyond the schema. The required 'message' parameter is obvious from the tool'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?

The description clearly states the tool's purpose with specific verbs ('Report') and resources ('a bug, missing feature, or send feedback'). It distinguishes itself from sibling tools, which are all finance-related, making it unique.

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 guidance on when to use the tool and what to include ('Include the conversation array with recent messages for reproduction'). It does not explicitly state when not to use or alternatives, but the context is clear enough for a generic feedback tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by specifying the exact content (platform and adapter versions) without contradicting 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 directly conveys the tool's action. 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 no parameters and no output schema, the description adequately states the tool's function. Minor omission: could mention output format, but not critical for a simple version display.

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 the schema covers everything. The description adds no parameter info, but none is needed; baseline is 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?

The description clearly states the tool shows current MCP platform and adapter versions, which is specific and distinct from the sibling tools. No tautology or ambiguity.

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 tool's purpose is self-explanatory as a read-only version checker, but the description does not explicitly compare to siblings like toolkit_info or provide 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds specific context about what the return value includes, such as installed MCPs and their connection status, which provides value 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 a single sentence that is clear, direct, and contains no extraneous information. Every part is necessary.

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

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

The tool is simple with no parameters and no output schema. The description fully explains what the tool returns, making it complete for an informational 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; schema coverage is 100% by default. The description does not need to add parameter information. Baseline for 0 parameters is 4.

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

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

The description clearly states the tool returns toolkit state, specifically listing installed MCPs, connection status, and catalog tool counts. It uses a specific verb 'returns' and resource 'toolkit state', distinguishing it from siblings like show_version or report_bug.

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

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

No explicit guidance on when to use or not, but the read-only, idempotent nature implies it's safe to call anytime. Alternatives are not mentioned, but for a simple informational tool, this is acceptable.

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