XP MCP

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

The description adds behavioral context beyond annotations: it reveals that calling with no args returns a login link, that the token is a JWT, and that config-based login is permanent. Annotations already indicate idempotence, which aligns. 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 relatively concise, packing all essential information into one dense sentence. It front-loads the purpose and provides actionable instructions. Could be improved with clearer separation of scenarios.

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

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

The tool has no output schema, but the description does not specify the return value or possible errors. While the low complexity reduces the need, the missing output information leaves a gap for agents expecting a response format.

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 'token' parameter: it is a JWT string for session login, and omitting it returns a link. This adds meaning beyond the schema's bare type 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 authentication for MCP.AI in IDE agents, specifying two methods (config-based and session-based) with explicit verb 'log in' and resource 'access token'. It distinguishes from sibling tools like 'connect' by focusing on user authentication rather than external service 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 explains when to use each method: config-based for permanent, non-expiring connection, and token parameter for session-only login. It provides context but no explicit exclusions or alternatives, making it clear but not exhaustive.

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 readOnly/idempotent hints. The description adds value by detailing different return states (authenticated vs missing credentials) and the presence of connect_url, going beyond what annotations convey.

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, each adding unique value without redundancy. The structure front-loads the core 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 no parameters and no output schema, the description adequately covers the tool's behavior. It explains the two primary states and what is returned, though it could briefly note the lack of input requirements.

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 has no need to explain parameter meaning. Baseline score 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 clearly states the tool returns connection status and URLs, distinguishing between fully connected and missing credentials states. This verb+resource pair is well-defined and distinct from sibling tools.

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

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

The description implies usage for checking connection status but does not explicitly specify when to use this tool versus alternatives like 'authenticate' or 'openfinance_list_connections'. No when-not-to-use guidance is provided.

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, the description discloses substantial behavioral context: invoke runs tools even when not installed, returns connect links for credentials, returns checkout/top-up links when paid tools have empty wallets, and requires workspace owner/admin for writes. It also clarifies that invoke is one-off and does not add the MCP to the toolkit, which is valuable side-effect information.

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 and dense, but every sentence contributes substantive guidance. It is front-loaded with the core purpose and follows a logical workflow order. However, it is a single unbroken paragraph with no bullet points or structural breaks, which makes parsing more difficult than 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?

Given the tool's complexity and the absence of an output schema, the description covers most key behaviors: search/describe/invoke flow, install vs invoke, billing, permissions, prompt library, and write operations. The main gap is that the 'resume' action is not mentioned, and some parameters are never described, so it is not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the central action parameter and core flow (search → describe → invoke) and references tool_id, but many parameters such as limit, immediate, tier_slug, conversation, resume, report_context, and request_details are left entirely undocumented in both the schema and description. The narrative helps with the main workflow but does not fully compensate for 23 undocumented 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 is the mcp.ai marketplace: an in-platform catalog and runner for MCPs/tools. It distinguishes itself from sibling tools (OpenFinance actions, report_bug, etc.) by positioning marketplace as the meta-hub for searching, describing, invoking, and installing MCPs.

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

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

Provides explicit usage guidance: 'prefer invoke for a single/occasional use', 'use install only to make an MCP PERMANENT', and 'request_mcp asks us to build a NEW MCP when nothing fits'. It also explains when list_tools, subscribe/cancel, and prompt-library actions are appropriate, giving a clear decision framework.

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 behavioral context beyond the destructiveHint annotation: it revokes consent, deletes data, makes data unavailable, and returns a reconnection URL. This effectively communicates the outcome.

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

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

Three sentences, front-loaded with the main action, no unnecessary words. 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?

While the description covers the destructive action and reconnection possibility, it is incomplete because it fails to document the parameter's meaning. Given the simple input schema, this is a notable gap.

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

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

The parameter 'item' is required but has no description in the schema or the tool description. The description mentions 'specific bank' but does not explain how 'item' identifies the bank, leaving the agent without necessary semantic 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 uses specific verbs 'revokes' and 'deletes' to clearly state the action: revoking Open Finance consent for a specific bank and deleting connection data. It distinguishes this tool from siblings like listing connections or getting 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 implies when to use (when disconnecting a bank) but does not provide explicit guidance on alternatives or prerequisites. It mentions a reconnection URL but lacks context like 'use this when you want to permanently remove a bank connection'.

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?

Disclosures far exceed annotations: polling up to ~60s, return format, error states (needs_action with reconnect_url, timed_out), and fire-and-forget option. 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?

Single dense paragraph is efficient but could be broken into bullet points for scanability. Key action is front-loaded; 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 no output schema and complexity (sync operation, multiple modes, error handling), the description is comprehensive: covers return structure, edge cases, and usage guidance. Enough for an agent to correctly invoke.

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 both parameters: 'wait' (boolean to choose blocking/non-blocking) and 'items' (array of selectors, omit for all). Adds meaning beyond schema structure.

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 ('Forces the bank to re-sync') and resource ('one or more connections') with clear behavior ('NOW and WAITS for it to finish'). It distinguishes from sibling tools that are read-only or involve disconnection.

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 a balance or transaction list looks stale') and what it avoids ('WITHOUT disconnecting/reconnecting'). Does not explicitly mention when not to use or compare directly to sibling read tools, but context is sufficient.

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. The description adds critical details: CREDIT accounts may return a warning instead of an error, and when upstream fails, the row degrades to last-synced balance with realtime=false and a warning. These go well 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 yet comprehensive. Every sentence adds value: main purpose, parameter format, error handling, degradation behavior, and response shape. No wasted words, well front-loaded.

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

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

Given no output schema, the description explains the response structure ({ results, errors }) and details warning scenarios. It covers normal and edge cases, making the tool's behavior 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 only specifies 'account_ids' as an array of strings with no description (0% schema coverage). The description fully compensates by specifying it must be an array of strings (1–50 items), which is essential 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 'real-time balance payload per account id' and specifies the endpoint (GET /accounts/:id/balance). It distinguishes from sibling tools like openfinance_list_accounts or openfinance_get_accounts_detail by focusing specifically 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?

Provides explicit guidance on passing account_ids as an array of 1–50 items. Describes behavior for CREDIT accounts and degraded responses when the institution is unavailable. However, it does not explicitly compare to alternative tools or state when not to use this 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 indicate readOnlyHint, idempotentHint, and non-destructive. Description adds critical behavioral context about the provider_incident block and data reliability warnings, advising not to present unreliable values as real. 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 concise with 4 sentences, each providing necessary detail: purpose, parameter usage, return shape, and a critical warning. No extraneous information; front-loaded with core function.

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 explains return shape partially (full account objects, batch wrap, provider_incident). Could elaborate more on the account object fields, but the essential caveats are covered. Annotations cover safety, so description complements well.

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?

Input schema only defines account_ids as an array of strings with 0% schema description coverage. Description compensates by specifying constraints (1-50 items), batch shape ({results, errors}), and the purpose of the parameter. Provides essential 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?

Description clearly states the tool returns full account objects with extended creditData per ID, specifying the HTTP endpoint and batch shape. It distinguishes from sibling tools like openfinance_list_accounts (list) and openfinance_get_account_balance (balance) by focusing on detailed credit information.

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?

Description explains how to use (pass account_ids as array 1-50) and warns about provider_incident, but does not explicitly state when to prefer this tool over alternatives or when not to use it. Usage is implied rather than directly contrasted with siblings.

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, destructiveHint), the description adds critical behavioral context: batch shape with results/errors, Pluggy missing paid/status, payment timing details, and the sparse/inconsistent billId hint on transactions. 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 longer than necessary, with parenthetical clarifications, but it is well-structured and front-loaded with the core purpose. Every sentence adds value, though some could be condensed.

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 fully explains the return shape (financeCharges, payments array with fields, batch results/errors). It also covers input, usage sequence, and connector-specific caveats, making it complete for a tool with one required parameter.

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

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

Schema has 0% description coverage, so description compensates by explaining the 'bill_ids' parameter is an array and advises to discover IDs via list_bills first. However, it does not detail the format of each ID or explicitly state that they come from that prior call.

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

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

The description clearly states the tool's function: 'Returns bill-level detail for one or more credit card bills by id'. It explicitly distinguishes from siblings by noting what it does NOT return (individual transactions) and directs to openfinance_list_transactions for itemized 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 when-to-use and when-not-to-use guidance: use openfinance_list_credit_card_bills first to discover ids, do not reconstruct bill total by summing transactions, and explains the nuance about payments in Brazilian Open Finance. It also warns about missing paid/status field.

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 context: the exact return fields (status, executionStatus, connector metadata, reconnect_url), and explains that the reconnect_url reopens the widget in UPDATE mode without disconnecting or using a connection slot. 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 concise at two sentences, yet packs all critical information. It front-loads the main function and then details variants. 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?

With no output schema, the description covers the return value (status, executionStatus, connector metadata, reconnect_url) and explains behavior for single vs. all banks, including bulk support. This is 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?

Schema description coverage is 0%, so the description must explain parameters. It explains 'item' and 'item_ids' thoroughly, but does not mention 'item_id', which is a separate parameter. This leaves a minor gap in parameter documentation.

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, lists possible statuses, and explains the difference between single and bulk retrieval. It distinguishes itself from sibling tools by focusing on status retrieval and reconnection URL.

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

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

The description provides clear usage guidelines: use 'item' for a single bank, omit for all banks, and 'item_ids' for bulk. It explains the reconnect_url's purpose. However, it does not explicitly mention when not to use this tool or compare to alternatives like 'openfinance_list_connections'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is a safe read. The description adds transparency about the batch response shape ({ results, errors }) and lists the exact fields returned, which enriches the behavioral model 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 paragraph that front-loads the main purpose and lists many fields. It is slightly verbose but every sentence earns its place by providing useful information. Could be trimmed slightly 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 simple read-only nature, the presence of a sibling list tool, and no output schema, the description comprehensively covers what is returned (detailed fields), the batch response format, and the HTTP method. No gaps remain for an agent 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 coverage is 0%, but the description adds meaning by specifying that loan_ids should be an array (1-50) of strings, implying they are loan IDs. While it doesn't detail ID format, the context and constraint are sufficient for correct invocation.

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 full loan contract detail by ID, specifying the HTTP method and path (GET /loans/:loanId). It lists the specific fields returned (interestRates, charges, etc.) and distinguishes itself from the sibling openfinance_list_loans by stating 'Use after openfinance_list_loans to deep-dive on 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 to use this tool after openfinance_list_loans for deep-diving, and provides usage constraints: pass loan_ids as an array of 1-50 items. This gives clear when-to-use and practical guidance.

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

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

Adds significant behavioral context beyond annotations, such as the connector-dependent meaning of credit balance, provider incidents that make data unreliable, and identity notices requiring deduplication. No contradiction with readOnlyHint or 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 long but well-structured, front-loading the core purpose and then detailing edge cases and caveats. While verbose, every section adds value for a complex tool.

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

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

Comprehensive coverage of tool behavior, including special blocks (provider_incident, identity_notice), return fields, and references to sibling tools. No output schema exists, but description compensates adequately.

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 the usage of item (target single bank) and item_ids (bulk), and implies type via context. However, the distinction between item and item_id is not fully clarified, leaving minor 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 accounts for bank connections, distinguishing between BANK and CREDIT types, and lists key fields. It also explicitly differentiates from sibling tools like openfinance_list_credit_card_bills for bill-related queries.

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 omit item (list across all banks) vs pass item (target single bank). Warns about not using credit balance as this month's bill and directs to the appropriate 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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds valuable behavioral details: the data is cached for the adapter session, it returns a single aggregated response, and there are no batch IDs. This enhances the agent's understanding of side effects and data structure.

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

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

The description is extremely concise—three sentences—and front-loaded with the primary purpose. Every sentence provides essential information without redundancy or unnecessary detail.

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 covers the response structure completely and mentions caching and aggregation. For a simple zero-parameter tool, this is adequately 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?

There are no parameters, so the description does not need to document them. However, it compensates by thoroughly describing the response fields (id, description, descriptionTranslated, parentId, parentDescription), adding meaning beyond the empty 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 the transaction category taxonomy, specifying the source (GET /categories) and the caching behavior. It is distinct from sibling list tools, but does not explicitly differentiate when to use it over alternatives.

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 mentions that the id is used by openfinance_update_transaction_category, implying a use case, but it does not provide explicit guidance on when to use this tool versus other list tools or how to handle the 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?

The description adds significant behavioral context beyond annotations: explains the reconnect_url behavior, that it does not consume a connection slot, and does not require disconnecting. 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 concise (4-5 sentences), well-structured, and contains no unnecessary information. 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?

For a read-only list tool with no parameters and no output schema, the description covers key aspects (return fields, special URLs, usage constraints). It is complete enough for an agent to use effectively, though minor details like pagination are omitted.

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, so the description does not need to document them. Baseline score of 4 applies as per rubric.

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 saved bank connections with specific fields (connector_id, item_id, bank name, etc.), distinguishing it from sibling tools like list_accounts or list_transactions. It 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 explains when to use the reconnect_url (for re-authentication cases) but does not explicitly compare to alternative tools for listing connections. However, the purpose is clear enough that an agent can infer when to call this 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?

Discloses detailed behavior including payment allocation logic, derived payment_status, connector asymmetry for open bills, bill grouping reliability. Annotations already mark it read-only; description adds extensive 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?

Very long description with dense information. While all details are relevant, it lacks conciseness and structure. Could be broken into sections.

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 domain complexity and lack of output schema, the description covers all necessary aspects: return fields, derived fields, optional modes, cross-bill logic, error handling. Very thorough.

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 explains account_id and include_open_bill with context. However, it omits page, page_size, and account_ids. So partial 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 starts with a clear verb 'Returns' and specifies the resource 'CLOSED credit card bills for a CREDIT-type account', listing key fields. It differentiates from sibling tools by mentioning not to use for 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?

Explicitly states when to use (to get closed bills), when to avoid (for transactions), and provides alternative tool name. Warns about misinterpreting payments array and naming conventions.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds critical behavior: error handling without exception, and detailed data integrity cross-checking for mass zeroing, flagging suspect rows. Goes well 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?

Front-loaded with main purpose, but the long data integrity paragraph could be condensed. Bulk support sentence at end. Adequate but not maximally 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?

Covers output structure (total, results, warning) and error handling. Missing details on pagination and type filter. For 6-param tool with no output schema, description should be more 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?

Schema coverage is 0%, description only mentions item_ids for bulk support. No explanation of page, page_size, type, item, or item_id parameters. Agent cannot infer their meanings from description alone.

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 returns investment portfolio for a connection, listing specific asset types (FIIs, stocks, etc.) and data fields. Differentiates from siblings like openfinance_list_investment_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 context on when to use (investments portfolio), error handling (returns empty response on 403), and bulk support. No explicit when-not-to-use or alternatives, but sibling names imply differentiation.

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. Description adds behavioral context by detailing the nature of data (movement history, transaction types) and the fields returned. 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?

Two sentences: first defines purpose and data fields, second gives usage guidance. No unnecessary words, front-loaded with key 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?

Describes return values (transaction types and fields) but does not explain pagination behavior or output format. Without an output schema, the description should cover what to expect, which is partially done.

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 description must compensate. It explains investment_id and investment_ids (bulk) but does not mention page or page_size parameters. Missing pagination semantics, but provides some context for the main 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 the tool returns movement history for a specific investment position, listing transaction types (BUY/SELL etc.) and fields (quantity, value, amounts, expenses). Distinguished from siblings like openfinance_list_investments and openfinance_list_transactions by specifying 'investment transactions' and referencing investment_id.

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 to use after openfinance_list_investments to obtain investment_id, and mentions bulk support for multiple investment_ids. Does not explicitly state when not to use, but 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 indicate readOnly and non-destructive behavior. Description adds detail on sequential querying with rate-limit spacing and per-connection result/error structure. 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?

Four sentences, front-loaded with purpose, then parameter details. Every sentence adds value with 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 simple schema (1 optional param) and no output schema, description covers all needed context: parameter usage, rate-limit behavior, return structure. 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?

Schema has 0% coverage, but description thoroughly explains the items parameter: array of connection selectors (item_id, connector_id, connector_name) and behavioral semantics (sequential, optional). Adds critical 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?

Description clearly states the tool lists loan contracts per bank connection, specifies the HTTP endpoint, and distinguishes from siblings like openfinance_get_loan_detail. Uses specific verb 'list' and resource 'loan contracts'.

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 instructions: pass items for specific connections, omit for all banks. Does not explicitly mention when not to use or alternatives, but the context is sufficient.

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 numerous behavioral traits beyond annotations: creditCardMetadata.billId being a sparse/inconsistent hint, PENDING vs POSTED variations, auto vs manual pagination, upstream error handling, detail parameter impacts, provider incidents, and bulk support. 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 comprehensive and well-structured, front-loading the purpose and logically organizing behavioral details. Though lengthy, every sentence adds value for a complex tool. A slight trim could enhance conciseness, but the current structure is effective.

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 (8 parameters, no output schema), the description covers all relevant aspects: output structure (account echo, truncated flag), error handling, provider incidents, connection health, bulk support, and parameter semantics. It is complete enough for an agent to use 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 compensates by explaining all parameters: from/to (ISO dates), search_queries (case-insensitive substring, OR semantics), page/page_size (pagination behavior), detail (enum with clear meanings), account_id (required), and account_ids (bulk). Adds substantial 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 (BANK or CREDIT type) and explicitly distinguishes itself from siblings like openfinance_list_credit_card_bills for standardized bill totals. It uses a specific verb and resource.

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 (only way for CREDIT itemized transactions) and when-not-to-use (do not reconstruct bill totals by billId; use openfinance_list_credit_card_bills instead). Also suggests alternatives for closing/due dates and connection health checks.

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 the tool as read-only, idempotent, and non-destructive. The description adds significant value by disclosing key behaviors: per-account transaction cap of 5000 with a truncated flag, the provider_incident block indicating potentially incomplete data, and the behavior of bulk mode. This goes well 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 front-loaded with the main purpose and provides detailed information in a coherent flow. It is somewhat dense and runs into a single paragraph, but every sentence adds value. It could be improved by breaking into sections (e.g., overview, parameters, output, edge cases), but overall it is 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 complexity (9 parameters, no output schema, 0% schema coverage), the description is remarkably complete. It describes the output structure (compact summary with fields like total entradas, por_mes, top_despesas, etc.), explains edge cases (truncated, provider incident), and covers all major usage scenarios including bulk mode. No output schema is needed as the verbal description suffices.

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 the purpose of most parameters: item, item_ids, from/to (ISO dates), granularity (monthly vs raw), detail (rich/raw), type, and top_n (implied through 'largest N'). However, the item_id parameter is not mentioned in the description, leaving a small 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 does consolidated cash-flow analysis for a bank connection in one call, with specific verb 'analyze' and resource 'connection transactions'. It distinguishes itself from siblings by noting that it internally resolves accounts, so there is no need to call openfinance_list_accounts first.

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

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

The description provides clear guidance on when to use the tool (e.g., for annual/monthly analysis, cash flow, top expenses) and when to use different granularities and details. It mentions bulk support and the ability to omit item to analyze all linked banks. However, it does not explicitly compare to the similar sibling openfinance_list_transactions, so some context is implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context: it checks a public status page, returns global indicator, degraded components, open incidents, and flags 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?

The description is three well-structured sentences, front-loading the main purpose. Each sentence adds value: purpose, usage scenario, output details. It is slightly lengthy but every part 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, the description fully explains what the tool returns (global indicator, degraded components, incidents, affected banks). It covers all needed context for a status-check tool with no parameters.

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%. The description does not need to add parameter information; the baseline score of 4 applies.

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

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

The description clearly states the tool checks the LIVE operational status of the Open Finance provider, using specific verbs and resources. It distinguishes from the sibling tool openfinance_get_item_status by explicitly noting it covers provider-side health versus connection health.

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: when data appears incomplete or stale despite a connection showing UPDATED. Also tells when not to use it (connection-specific issues) and 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?

Beyond annotations (readOnly, idempotent, not destructive), the description adds multiple behavioral traits: caveat about non-Open Finance connectors needing manual reconnection, plan-based visibility (PF hides PJ banks), and that missing keywords returns a hint instead of dumping the catalog. These significantly augment agent understanding.

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 paragraph with multiple sentences, but each sentence adds essential information. It front-loads the purpose and return details, then covers caveats, plan behavior, and usage guidance. Slightly verbose but 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 has 2 simple parameters and no output schema, the description fully covers input behavior, return fields, conditional behavior (caveats, plan limits), and error handling (missing keywords). No gaps are evident.

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 carries full burden. It provides examples for keywords (['nubank','btg']), explains include_accounts triggers account retrieval, and clarifies that keywords is REQUIRED despite schema marking it optional. This is comprehensive and actionable.

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 specifies the verb 'searches' and the resource 'bank connectors', with detailed return fields (connector id, access, audience, linked connections, accounts, connect_url). It clearly distinguishes from sibling tools by emphasizing its role in providing a ready connect_url and pre-selecting the bank.

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 'Call this BEFORE connecting to hand the user a one-click link', giving a clear sequence. It also advises surfacing caveats to prefer Open Finance connectors for automation, but does not explicitly contrast with specific sibling tools or list when not to use.

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 behavioral traits beyond annotations: overrides automatic categorization, teaches Pluggy via rule creation, batch error handling (per-item errors don't fail whole batch). 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?

Efficient single paragraph, front-loaded with purpose. Dense but well-organized. Minor opportunity for bullet points or shorter sentences.

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?

Thorough for a batch update tool with side effects. Covers API endpoint, parameter construction, side effects (rule creation), and response shape. No output schema, but description fills that gap.

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

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

Adds full meaning to the only parameter (items) with structure, required fields, and sources. Compensates for 0% schema coverage with clear, actionable details.

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 'Corrects the category of one or more transactions' with HTTP method, resource, and direct action. Distinguishes from sibling tools like listing tools. No 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?

Explains how to structure the items array and provides sources for transaction_id and category_id. Describes the side effect (creates a Category Rule) and ideal use cases. Slight lack of explicit when-not-to-use, but effectively covers usage 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 contradicts the annotation 'idempotentHint: true' because reporting a bug typically creates a new record each time, not idempotent. No additional behavioral context 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?

Single concise sentence front-loads purpose. Could improve structure but 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?

Missing explanation of return values, side effects, or post-report behavior. Annotation contradiction further 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 only mentions the conversation parameter weakly, leaving 'message' and 'context' unexplained.

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 'Report a bug, missing feature, or send feedback,' specifying the verb and resources. It distinguishes from sibling tools which are mainly openfinance operations or utilities.

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

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

The description gives clear context that this tool is for reporting issues or feedback. It hints at including conversation array, but does not explicitly exclude any scenarios or mention 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds no behavioral context beyond stating it 'shows' versions, which aligns with these hints. There is no contradiction, but no extra value is added.

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

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

The description is a single, concise sentence with no unnecessary words. It is front-loaded and effectively communicates the tool's 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, no output schema, and a simple purpose, the description is almost complete. It could mention the expected return format (e.g., a string or object), but the low complexity makes this a minor omission.

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, and the schema coverage is trivially 100%. The baseline for zero parameters is 4, and no additional parameter explanation 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 shows current MCP platform and adapter versions. This is a specific verb+resource combination that distinguishes it from sibling tools, which focus on authentication, finance operations, or bug reporting.

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; it is obvious when to use it to check versions. While no explicit alternatives or when-not-to-use guidance is provided, the simplicity and distinctness from siblings make the usage context 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 safe read-only behavior. Description adds specific details about returned fields (installed MCPs, connection status, catalog counts), which is valuable 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?

Single sentence, front-loaded with main purpose, 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?

Explanation of return values is sufficient for a simple info tool 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?

No parameters, so schema covers all. Description adds value by explaining the purpose of the returned data, but no param details 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?

Specific verb 'Returns' with clear resource: toolkit state including installed MCPs, connection status, and catalog tools counts. Distinguishes from sibling tools which are mostly action-oriented.

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?

Describes what it returns but does not explicitly state when to use or when not to use. Context implies it's for diagnostics, but lacks alternatives.

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