PicPay MCP

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

Annotations already indicate idempotent and non-destructive. The description adds context about required user actions (copy token, paste), and behavior when called with no arguments (returns link).

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 slightly verbose but efficiently covers both authentication methods. Front-loaded with purpose and audience.

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 simple schema and no output schema, the description adequately covers authentication flows, token format, and no-arg behavior. Lacks return value details but acceptable.

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 thoroughly explains the sole parameter 'token': it's a JWT from browser login, optional for getting link, required for session authentication.

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 authenticates for MCP.AI IDE agents, explaining both permanent and session-based methods. It distinguishes from siblings like connect and marketplace by focusing on user authentication.

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

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

The description provides explicit instructions for two usage scenarios: adding token to config for permanent access or pasting token for session-only. It does not explicitly exclude alternatives, but the scope 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, idempotentHint=true, destructiveHint=false. Description adds behavioral context by explaining response based on state (authenticated vs missing credentials), which is beyond annotations.

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

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

Two sentences, front-loaded with main purpose, no extraneous information. Highly concise and well-structured.

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

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

For a zero-parameter tool with good annotations, the description provides sufficient context to understand what to expect. However, missing explicit return structure details could be improved.

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 baseline 4. Description adds value by explaining what the return contains in different states, partially compensating for 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?

Description clearly states it returns connection status and URLs with examples for different states. Verb 'returns' specifies action and resource. However, it does not explicitly distinguish from sibling tools like authenticate, which is related.

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?

Implied usage: check connection status. No explicit when-to-use or alternatives. Lacks guidance on when to use this vs authenticate or other connection-related tools.

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

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

Annotations indicate write operations (readOnlyHint false) but the description adds crucial behavioral details: invoke runs a tool without installing it, writes require owner/admin, and it describes exactly what happens when credentials or wallet are missing (returns connect/checkout links). This fully compensates for the lack of annotation details.

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

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

The description is dense and front-loaded but contains run-on sentences and extraneous details (e.g., 'consulta um CPF'). It could be more concise and better structured with bullet points for clarity.

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 (multiple actions, 13 parameters, no output schema), the description covers the main flows, permission requirements, and edge cases. However, it does not describe the output format for each action, leaving some ambiguity for the agent.

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?

While the description explains the main parameters (action, query, mcp_id, tool_id, arguments) in context of the flow, it does not document all 13 parameters (e.g., limit, immediate, tier_slug). Schema description coverage is 0%, so the description must compensate heavily; it partially does for key parameters but leaves gaps.

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

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

The description clearly states it is THE official mcp.ai marketplace for discovering and running MCPs/tools. It distinguishes from sibling tools by saying to use this tool first before external registries, and explains the core actions (search, describe, invoke) with their specific roles.

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

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

The description explicitly tells when to use this tool (when user wants a capability) and when not to (prefer external registries). It provides clear alternatives: use install for permanent addition, invoke for one-off use, list_tools for callable tools now. It also outlines prerequisites like workspace owner/admin for writes.

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?

Describes the destructive nature beyond annotations (deletes data, data no longer available) and mentions the return value, providing comprehensive behavioral context.

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

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

Two concise sentences front-load the action and effect, with no wasted words.

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

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

Covers the main action, effect, and return value, but the ambiguous parameter prevents full completeness for a one-param 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 coverage is 0% and the description does not specify what the 'item' parameter represents (e.g., connection ID or bank name), leaving ambiguity for the agent.

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

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

The description clearly states it revokes consent and deletes connection data for a specific bank, differentiating it from siblings like openfinance_list_connections. It also mentions the return of a reconnect 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 implicitly indicates when to use (to disconnect a bank) and provides the reconnection hint, but lacks explicit guidance on when not to use or 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?

Discloses key behaviors: waits up to 60s, polling mechanism, return fields (status, executionStatus, lastUpdatedAt, synced, needs_action, timed_out). Annotations (readOnlyHint=false, destructiveHint=false) are consistent with a state-changing sync operation. 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 thorough but not overly verbose. It is well-structured: purpose, use case, parameter details, return value breakdown, error handling. Could be slightly tighter but each 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 two parameters and no output schema, the description covers all essential context: how to invoke, return format, error states, timeout behavior, and post-sync actions. It is complete for an agent to select and use 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 both parameters: 'wait' (fire-and-forget vs blocking) and 'items' (array of selectors or omitted for all). Adds concrete examples and behavior, compensating completely for the 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 forces a bank to re-sync connections and waits for completion. It specifies the verb 'forces', the resource 'connections', and the mode 'now and waits'. It distinguishes itself from sibling tools by noting it does not disconnect/reconnect, and provides a specific use case.

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'. Also provides guidance on what to pass (items array) and when to omit (sync all). It contrasts wait=true vs false, and tells the user to re-check with openfinance_get_item_status if timed_out.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds real-time behavior, error handling specifics (structured warning for credit accounts), and response 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?

Two concise sentences plus a response shape snippet. Front-loaded with purpose and endpoint, no redundant or irrelevant information. Every sentence earns its place.

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

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

Given the simple tool (one required parameter, no output schema, clear annotations), the description covers endpoint, parameter constraints, error behavior, and response structure adequately. No missing context needed for correct invocation.

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

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

Schema description coverage is 0%, but the description compensates by explaining the account_ids parameter as an array with a recommended size (1–50). This adds significant meaning beyond the schema's minimal array-of-strings 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?

Description clearly states the tool returns a real-time balance payload per account id, specifies the HTTP endpoint, and distinguishes from sibling tools (e.g., list_accounts, get_accounts_detail) by focusing on balance retrieval and error handling for credit accounts.

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

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

Explicitly instructs to pass account_ids as an array (1–50) and warns that credit accounts may return a BALANCE_FETCH_ERROR with a structured warning instead of an exception. Lacks explicit when-not-to-use vs alternatives, but context from sibling names and the specific purpose provides sufficient 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. Description adds valuable behavioral context: batch shape with results/errors, and that it returns extended creditData. No contradictions with annotations. Could mention rate limits or idempotency implications.

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

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

Two concise sentences: first states purpose and endpoint, second gives parameter and response shape. No extraneous 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?

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, parameter usage, and response structure. It lacks examples or explanation of 'extended creditData', but overall is sufficient for an agent to use 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 compensates by specifying the parameter is an array of IDs, with a batch size limit of 1–50, and the response structure. This adds meaning beyond the bare schema. Could be more detailed on the format of account_ids (e.g., string 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?

Description clearly states it returns full account objects for specific IDs, including extended creditData. It specifies the endpoint (GET /accounts/:id) and batch processing. This distinguishes it from sibling tools like openfinance_list_accounts, which likely returns all accounts without detail.

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

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

Description implies usage context: when you have specific account IDs and need full details. It gives constraints (1–50 array) and response shape. However, it does not explicitly state when not to use it or mention alternatives like openfinance_list_accounts.

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, and no destructiveness. The description adds critical context: the batch {results, errors} shape, that Pluggy lacks a paid/status field, and the semantic nuance of payments[] relating to the previous bill's payment. 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 relatively long but well-structured: main function first, then exclusions and pointers, then batch shape, then a notable behavioral caveat. Every sentence earns its place, though some agents might benefit from slightly more 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 no output schema, the description adequately explains the return shape (financeCharges, payments, {results, errors}). It also provides critical domain context (Brazilian Open Finance, payments[] meaning) and cross-references sibling tools for discovery and status checking.

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 that bill_ids should be obtained from openfinance_list_credit_card_bills and that it's an array. This adds essential meaning beyond the schema's 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 it returns bill-level detail for credit card bills by ID, explicitly distinguishes from transaction-level tools by stating what it does NOT return, and points to openfinance_list_transactions for itemized transactions. This differentiates it well from siblings.

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

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

The description provides explicit guidance: use openfinance_list_credit_card_bills first to discover bill IDs, notes the meaning of payments array in Brazilian Open Finance, and recommends a sibling tool to check paid status. It also warns against assuming payment status from payments[].

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, so the tool is safe. The description adds value beyond annotations by detailing the return format (status values, count/items structure) and the effect of the `item` parameter, providing full transparency.

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

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

The description is two sentences with no wasted words. The first sentence states the core functionality, and the second explains the two usage modes. 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, the description sufficiently explains the return values and structure (status, executionStatus, metadata, and count/items wrapper). It is complete for a status-check tool with single optional parameter.

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

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

The schema has 0% description coverage for the `item` parameter. The description fully compensates by explaining that omitting `item` returns all banks (with a wrapped response) and passing it returns a single bank's status, providing essential semantic clarity.

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

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

The description explicitly states it returns the current status of a bank connection, listing possible status values (UPDATED, UPDATING, LOGIN_ERROR, etc.), executionStatus, and connector metadata. It distinguishes between fetching status for all linked banks vs. a single bank, which differentiates it from sibling tools like openfinance_list_connections or openfinance_provider_status.

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

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

The description provides clear usage guidance: omit `item` to get status for all linked banks or pass `item` for a single bank. It does not explicitly state when not to use the tool or mention alternatives, but the two modes cover common use cases.

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

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

Adds significant behavioral context beyond annotations (readOnlyHint): explains that 'name' is the legal entity not brand, CREDIT balance meaning is connector-dependent, and billing cycle dates. 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?

Front-loaded with main purpose, but subsequent sentences add dense detail (e.g., connector-dependent balance) that could be streamlined. Still efficient given the wealth of critical information, but slightly long.

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?

Thoroughly covers output fields, parameter usage, and caveats. Without output schema, description explains return values comprehensively. Directs to sibling tool for related functionality.

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 'item' parameter usage is well described via omission/passing guidance, but the 'type' parameter is only implied in output context (BANK/CREDIT) and not explicitly stated as a filter. With 0% schema coverage, description should directly define both parameter semantics.

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

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

The description clearly states the tool lists accounts (BANK/CREDIT) with specific fields like balance, number, type, subtype, bankData, creditData. It distinguishes from siblings like openfinance_list_credit_card_bills by mentioning alternatives and unique output details.

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 omit 'item' (list all banks) vs pass 'item' (single bank), and warns about CREDIT balance being connector-dependent, directing to openfinance_list_credit_card_bills for standardized amounts. Also clarifies using 'bank' instead of 'name' for user-facing text.

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, destructiveHint=false. The description adds that results are cached for the adapter session, which is useful behavioral context beyond what annotations provide. 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?

Three sentences, each concise and informative. Front-loaded with the core purpose, then details on entry structure and usage notes. 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?

Despite no output schema, the description fully explains the response structure: id, description, descriptionTranslated, parentId, parentDescription. It also clarifies caching and that it's a single aggregated response (no pagination or batching). Complete 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?

No parameters exist (schema coverage 100%). Description does not need to add parameter semantics; baseline for zero parameters is 4. It could potentially note that no parameters are needed, but it already implies that by stating 'Single aggregated response — no batch ids.'

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 for the session, and specifies it corresponds to GET /categories. This distinguishes it from sibling tools like openfinance_list_transactions; it is the only category-specific 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?

Explicitly mentions that the 'id' field is used by openfinance_update_transaction_category, guiding when to use this tool prior to updating categories. It also notes that descriptionTranslated is preferred for pt-BR users, providing user-specific guidance. It does not explicitly exclude other contexts, 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 provide readOnlyHint, idempotentHint, destructiveHint, so safety is clear. Description adds the returned fields but no additional behavioral traits like external calls or pagination.

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, well-structured sentence with key information 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?

For a parameterless listing tool with good annotations, the description is fairly complete. Could mention if result is paginated or sorted, but not critical.

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

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

No parameters, schema coverage 100%, so baseline is 4. Description does not need to add parameter info.

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 and specifies the returned fields (connector_id, item_id, bank name, add_connection_url). It distinguishes from sibling list tools like openfinance_list_accounts 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?

No guidance on when to use this tool versus alternatives, no prerequisites or context for selection among the many list tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds extensive behavioral context about payment_status derivation, cross-bill payment logic, and connector-specific limitations, far exceeding 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?

Description is long but front-loaded with core purpose. Structured with clear sections (IMPORTANT, CONNECTOR ASYMMETRY). Every sentence adds value, though some could be tightened.

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 complex tool with no output schema, the description thoroughly covers output fields, edge cases, derived logic, and links to related tools. It is complete despite the tool's intricacies.

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 has 0% description coverage. Description explains include_open_bill and account_ids (bulk), but does not explain page/page_size or account_id individually. It adds moderate value over 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 it returns CLOSED credit card bills for a CREDIT-type account, listing specific derived fields. It distinguishes itself from the sibling openfinance_list_transactions by noting that tool provides itemized purchases.

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 this tool vs alternatives: for bill-level summaries, not transactions. Also explains opt-in for open_bill and warns about connector asymmetry and payment semantics.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description adds value by detailing error handling: returns {total, results, warning} instead of throwing errors on 403 or upstream issues. This goes 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 packs a lot of information, which is efficient but slightly dense. It could be split for readability. 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 output schema, the description explains return values and error handling well. However, it lacks parameter semantics, which is a gap for a tool with 4 parameters and 0% schema coverage. Complexity is moderate.

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. However, it does not explain the input parameters (item, page, type, page_size). It only describes return fields. Minimal compensation for missing 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 it returns the investment portfolio for a connection, listing many specific types (FIIs, stocks, ETFs, etc.), which is a specific verb+resource. It distinguishes itself from sibling tools like openfinance_list_investment_transactions by focusing on the overall portfolio rather than transactions.

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

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

The description implies usage for retrieving investment portfolio data, but does not explicitly state when to use this tool vs alternatives (e.g., openfinance_list_investment_transactions). No exclusions or when-not-to-use guidance 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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by detailing the returned columns (quantity, value, amount, netAmount, agreedRate, brokerageNumber, expenses breakdown) and the bulk execution capability. 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: two short paragraphs. The first paragraph immediately conveys the core purpose and return data. The second adds usage and bulk support without redundancy. 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 4 parameters, no output schema, and annotations covering safety, the description explains the return structure in sufficient detail and provides usage context. The absence of output schema is partially offset by listing the columns. However, pagination behavior and limits are not mentioned.

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 that investment_id comes from openfinance_list_investments and that investment_ids enables bulk execution. However, it does not explain the page and page_size parameters, leaving some ambiguity for those fields.

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

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

The description starts with 'Returns the movement history for a specific investment position' which clearly states the verb (returns), resource (movement history), and scope (specific investment). It lists transaction types (BUY/SELL/TAX/INTEREST/AMORTIZATION/TRANSFER) and mentions use after openfinance_list_investments, distinguishing it from sibling tools like openfinance_list_investments.

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

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

The description says 'Use after openfinance_list_investments to get the investment_id' which provides explicit sequential usage guidance. It also mentions bulk support via investment_ids. However, it does not explicitly state when not to use this tool or list alternative tools for different 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals that multiple connections are fetched sequentially with rate-limit spacing and the return format is { results, errors } per connection. No contradiction with annotations.

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

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

Three sentences, front-loaded with the core purpose, each sentence adding essential information without redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema, strong annotations), the description covers all necessary aspects: purpose, input semantics, usage modes, behavior, and return format. 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?

The input schema has 0% coverage (no description) for the single parameter 'items'. The description compensates fully by explaining it is an array of connection selectors (item_id, connector_id, or connector_name) and how usage differs between providing and omitting it.

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 lists loan contracts, specifies the REST endpoint (GET /loans), and explains the two modes: with items for specific connections or omitted for all banks. This distinguishes it from sibling list tools like openfinance_list_accounts.

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 direction on when to use each mode (pass items for specific connections, omit for all), and mentions sequential querying with rate-limit spacing. However, it does not explicitly state when not to use or list alternatives, though the purpose is specific enough.

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=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral details: auto-pagination with a 5000 ceiling, truncation warning, error handling (returns placeholder instead of throwing), and differences in CREDIT PENDING/POSTED coverage per connector. 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 long but well-structured, front-loading the core purpose and then logically branching into CREDIT specifics, pagination, detail levels, error handling, and related tools. Every sentence adds value, though some trimming of verbose explanatory phrases 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 (8 parameters, no output schema, multiple sibling tools), the description covers all necessary aspects: purpose, usage distinctions, parameter details, behavioral nuances, error handling, and references to sibling tools for supplementary info (e.g., openfinance_get_item_status for connection health). It is exceptionally complete.

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

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

The input schema has 0% description coverage, so the description carries full burden. It explains all 8 parameters: account_id (required), account_ids (bulk), from/to (ISO dates), page (omit for auto-pagination), page_size (max 500), detail (enum with defaults and benefits), and search_queries (OR semantics, substring match). It also clarifies the default pagination behavior and the effect of detail levels on data richness.

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 transactions for bank accounts (BANK or CREDIT types). It differentiates from sibling tools like openfinance_list_credit_card_bills by specifying that for CREDIT accounts this is the only way to get itemized transactions, and that each transaction links to a bill via creditCardMetadata.billId.

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

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

It provides explicit guidance on when to use this tool vs alternatives: for CREDIT accounts, it's the only way to get itemized transactions; for standardized bill totals, use openfinance_list_credit_card_bills. It also explains when to use different detail levels and pagination modes, and advises narrowing from/to if truncated:true is returned.

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 and idempotent behavior. The description adds significant behavioral context: internal account resolution, fan-out of transactions, truncation cap at 5000/account with a 'truncated' flag, and the trade-offs between 'granularity:monthly' (compact summary) and 'granularity:raw' (heavier with full rows). 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 relatively long but front-loaded with the main purpose. It uses a logical flow: main purpose, then parameter details, then use cases. Every sentence adds value, though some phrasing could be tightened. The structure is effective 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?

Given the tool's complexity (7 parameters, no output schema, no required parameters), the description is remarkably complete. It covers the purpose, all parameters, behavioral details (truncation, granularity effects, detail options), and output structure (compact summary fields, raw rows, truncation flag). There are no missing pieces.

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 most parameters: 'item' as connector_id/connector_name/item_id, 'from'/'to' as ISO dates, 'granularity' with behaviors, 'detail' with three options and their effects, and 'type' for filtering BANK/CREDIT. However, 'top_n' is only mentioned in output context (largest N) and not explicitly linked to the parameter; also, date format is mentioned but not validated against schema. Overall, it covers the majority well.

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: consolidated cash-flow analysis for a bank connection over a period. It specifies the verb ('analyze' implied), resource ('bank connection transactions'), and distinguishes from siblings like openfinance_list_accounts by noting you don't need to call it first. The description also covers alternative usage by omitting the 'item' parameter.

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

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

The description provides clear context on when to use this tool, including specific analysis types (análise anual/mensal, fluxo de caixa, etc.) and when to use 'granularity:raw' for itemized rows. It also explains that the tool resolves accounts internally, so you don't need to call openfinance_list_accounts. However, it lacks explicit 'when not to use' statements, though 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the live nature of the check and the output fields (global indicator, degraded components, open 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?

The description is concise and well-structured, starting with the main purpose, then usage guidance, followed by output details. Every sentence adds value without redundancy.

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

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

Given no parameters and no output schema, the description provides complete context: what the tool does, when to use it, and what it returns. Annotations cover safety. 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?

The tool has no parameters, so schema coverage is 100%. The description does not need to add parameter information, and it provides sufficient context about the tool's behavior without referencing 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 checks the LIVE operational status of the Open Finance provider, distinct from connection status. It uses specific verbs ('checks', 'reveals') and explicitly distinguishes from sibling tool 'openfinance_get_item_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 explicitly tells when to use this tool: when data looks incomplete or stale even though a connection shows UPDATED. It explains the tool reveals upstream outages or incidents, differentiating provider-side problems from connection issues.

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 key behavioral traits: returns connector metadata, linked connections, accounts if requested, and a connect URL. Also warns about caveat for non-Open-Finance connectors that need manual reconnection. Complements annotations which already indicate read-only and idempotent 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?

Every sentence adds value, no redundancy. The description is front-loaded with the main purpose and flows logically into usage, parameters, and behavioral notes.

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

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

Comprehensive for a search tool with two parameters and no output schema. Covers purpose, input requirements, return fields, caveats, and workflow integration. No gaps for an agent to misuse the 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?

Both parameters are explained with examples (keywords[] with e.g., include_accounts with behavior). However, the description says keywords is required while the schema does not mark it required, creating a slight inconsistency.

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 and returns specific fields. It distinguishes itself from siblings like 'connect' and 'list_connections' by positioning itself as a pre-connect search step.

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

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

Explicitly instructs to call this BEFORE connecting, mentions that keywords are required (otherwise returns a hint), and notes plan-based filtering. Provides clear when-to-use and what it should not be used for (never dump the whole catalog).

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 goes well beyond the annotations (which provide no behavioral clues) by disclosing that the tool overrides Pluggy's automatic categorization and teaches Pluggy by creating a Category Rule for the client. It also details batch behavior (per-item errors don't fail the whole batch) and the return shape. This is excellent transparency for a mutation tool.

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 action and then expands on effects and error handling. Every sentence provides value, though it is somewhat lengthy. It is well-organized but could be slightly tighter without losing clarity.

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

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

Given that there is no output schema, the description fully describes the return structure ({ updated, results, errors }) and error semantics (per-item errors don't fail the whole batch). It also covers prerequisites (IDs from other tools) and side effects (Category Rules). This makes the tool completely understandable without external documentation.

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?

Although the schema description coverage is 0%, the description compensates by explaining the structure of the `items` array (array of { transaction_id, category_id }) and provides context on where to obtain each ID. It clarifies the intended use of the parameters, adding semantic value beyond the raw schema.

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

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

The description clearly states the tool corrects transaction categories, specifies the HTTP method and path (PATCH /transactions/:id), and distinguishes it from sibling tools like openfinance_list_transactions and openfinance_list_categories. It uses a specific verb ('corrects') and identifies the resource (transaction categories), making the purpose unambiguous.

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

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

The description explains exactly when to use this tool (fix miscategorized transactions), provides sources for required IDs (transaction_id from openfinance_list_transactions, category_id from openfinance_list_categories), and describes the behavioral impact (creates Category Rules for future similar transactions). It implicitly contrasts with listing tools but does not explicitly state when not to use it, which would improve 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 indicate idempotent and non-destructive behavior. The description does not add further behavioral details (e.g., processing time, rate limits), but does not contradict annotations.

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

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

Two concise sentences provide essential information without extraneous content.

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

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

For a simple feedback tool without output schema, the description covers primary usage. Could note that 'message' is required, but overall it is complete enough for correct 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 0% schema coverage, description partially compensates by explaining the conversation parameter. However, 'context' parameter remains unexplained, and no format details are given for the conversation string.

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: reporting bugs, missing features, or sending feedback. It is distinct from sibling tools, which focus on financial operations.

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

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

It instructs to include the conversation array for reproduction, providing clear context. No exclusions or alternatives are needed since no sibling tool serves the same function.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds the specific output (MCP platform and adapter versions), which provides useful 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?

The description is a single sentence, very concise, and front-loaded with the key action and resource. There is no wasted text.

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 fully explains what the tool returns (current MCP platform and adapter versions) and there are no parameters. This is complete for a simple version 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, and schema description coverage is 100%. The description adds no parameter information because none is needed.

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

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

The description clearly states the tool's purpose: showing current MCP platform and adapter versions. It uses a specific verb ('Show') and resource, and it is easily distinguishable 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?

No explicit guidance on when to use this tool vs. alternatives is provided. The context is implied—it's a simple version display—but there is no mention of when not to use it or of alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying the exact output content (MCPs, connection status, catalog counts), providing 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?

The description is a single, front-loaded sentence that directly conveys the tool's purpose without any extraneous information.

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

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

For a simple info tool with no parameters or output schema, the description is sufficiently complete, detailing the three components of the returned state.

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 appropriately does not mention parameters. It adds no redundancy and fully leverages 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 the tool returns the current toolkit state with specific components: installed MCPs, connection status, and catalog tool counts. It uses a specific verb ('Returns') and resource, distinguishing it from sibling tools like show_version.

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 retrieving toolkit state but does not explicitly state when to use this tool over alternatives. However, given its zero-parameter read-only nature, 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.