SafraPay MCP

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

The description explains the user interaction required (browser login, copying token) and the two outcomes (permanent vs session login). It aligns with annotations (idempotentHint=true) and does not contradict them. However, it does not detail the response format or error handling for invalid tokens.

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, immediately states the purpose, and presents the two usage options efficiently. Every sentence provides essential information 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 the tool's simplicity (one optional parameter, no output schema), the description covers the key behavioral aspects and usage modes. It is slightly incomplete in not mentioning the expected output (e.g., success message or link), but this is a minor 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 schema has one parameter 'token' with 0% coverage, but the description fully explains its meaning: when provided, it logs in session-only; when omitted, it returns a login link. This adds complete 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 identifies the tool's purpose: authenticating for MCP.AI IDE agents. It specifies the login process and two distinct modes (permanent config or session token), effectively distinguishing it from sibling tools like 'connect'.

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 guides when to use the tool: for logging in, and how to use it with or without a token. It provides clear context for the two usage scenarios, though it does not explicitly state when not to use this tool in favor of 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 declare readOnlyHint true, idempotentHint true, destructiveHint false. The description adds further detail on return values (authenticated, pending, connect_url), providing complete behavioral context without contradiction.

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

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

Two sentences, each carrying essential information. No wasted words; front-loaded with the key purpose.

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

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

For a tool with no parameters and no output schema, the description covers all relevant scenarios (connected vs missing credentials) thoroughly. No gaps remain.

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

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

No parameters exist, so the baseline is 4. The description correctly adds no parameter information, which 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, and distinguishes between two key states: all providers connected vs missing credentials. This differentiates it from sibling tools like 'authenticate' 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 explains when the tool is useful (checking connection status) and hints at scenarios (all connected vs missing credentials). It does not explicitly state when not to use it, but the context is clear enough.

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

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

The description discloses behaviors beyond annotations: it explains that 'invoke' works without installing, returns connect/checkout links when needed, and that writes require permissions. There is no contradiction with annotations; the description adds valuable 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?

The description is dense but well-organized, covering core flow, key behaviors, and a list of actions. It is not overly concise but every sentence adds value. A more structured format (e.g., bullet points) could improve readability.

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 the complexity of 13 parameters and no output schema, the description thoroughly covers usage flow, permissions, and edge cases (e.g., credential/wallet issues). It provides sufficient context for an AI 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 13 parameters and 0% schema description coverage, the description compensates by explaining the core flow and the purpose of key parameters (e.g., 'action', 'mcp_id', 'tool_id', 'arguments'). However, it does not systematically describe all parameters, leaving some ambiguity for an AI agent.

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

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

The description clearly states the tool is the official marketplace for discovering and running MCPs. It distinguishes itself from sibling tools like 'authenticate' or 'openfinance' by being a meta-tool. The core flow and actions are explicitly defined.

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 THIS tool FIRST' for capability discovery, differentiates between 'invoke' (one-off) and 'install' (permanent), and notes that write actions require workspace owner/admin. It offers clear context for when to use each action.

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

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

Annotations already indicate destructiveHint=true, and the description adds specific behavioral details: data deletion, unavailability, and return of reconnection URL, which supports the destructive nature.

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 succinct sentences: first states the core action, second explains consequences and return value. No superfluous words.

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

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

The description covers the main purpose and effect but omits parameter explanation and does not mention potential errors or prerequisites, leaving some gaps for a simple tool.

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

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

The single parameter 'item' has 0% schema description coverage, and the description does not explain what 'item' represents (e.g., bank identifier), leaving the agent unable to infer its meaning.

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

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

The description clearly states the action ('Revokes the Open Finance consent') and the resource ('specific bank' and 'connection data'), distinguishing it from sibling tools like 'openfinance_list_connections'.

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

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

The description implies when to use (to disconnect a bank) but lacks explicit guidance on when not to use or alternatives. The mention of a reconnection URL provides context but no direct comparison to other 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?

Describes the synchronous polling behavior (up to ~60s), possible outcomes (needs_action, timed_out), and side effects (data refresh). Annotations show readOnlyHint=false, consistent with the mutation action. 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?

Every sentence is purposeful, with a logical flow: action, use case, parameters, return format. No redundant information, yet comprehensive. Front-loads the key behavior.

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 details the return structure with fields like status, executionStatus, lastUpdatedAt, synced, needs_action, and timed_out. Covers error states and edge cases, making it complete for this complex sync 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?

Despite 0% schema coverage, the description fully explains both parameters: `items` as an array of selectors (item_id, connector_id, connector_name) and `wait` as a boolean for fire-and-forget mode. Omission of `items` means sync all linked banks.

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 PATCH/polling mechanism and distinguishes from siblings like openfinance_get_item_status by noting it as a re-check alternative.

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 (stale balance/transactions) and when not to (no need to disconnect/reconnect). Also provides guidance for handling timed-out syncs by using openfinance_get_item_status.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavior: CREDIT accounts may return a structured warning instead of throwing an error, and the response shape is outlined. This goes 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 three sentences long, front-loaded with the core purpose, and includes only necessary details. No extraneous information.

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

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

Given no output schema, the description provides the response shape and error handling. The warning behavior for CREDIT accounts is included. For a simple read tool, all relevant context is covered.

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 that account_ids is an array of strings with a size limit of 1-50. It also hints at the usage via the endpoint path. This adds 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 'Returns real-time balance payload per account id' with the specific HTTP endpoint and required input. It distinguishes itself from sibling tools like openfinance_list_accounts and openfinance_get_accounts_detail by focusing exclusively on balance retrieval.

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

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

The description provides a constraint on the input array size (1-50) but does not explicitly state when to use this tool over alternatives or when not to use it. The context of siblings implies it's for balance queries, but no direct guidance is given.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the batch shape and array limit, which go beyond annotations. 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 concise sentences front-loaded with the main purpose. Every sentence adds value with no wasted words.

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

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

No output schema, but the description gives the batch shape. It covers input constraints and return structure adequately for a low-complexity tool. Could mention authentication but that's handled by sibling authenticate.

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 provides no description (0% coverage). The description compensates by specifying array size limits (1–50) and the return shape, adding significant value beyond the schema.

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

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

The description clearly states the verb ('Returns'), the resource ('full account objects including extended creditData'), and the endpoint ('GET /accounts/:id'). It distinguishes from sibling tools like openfinance_list_accounts by implying detail vs list.

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 passing `account_ids` as an array (1–50) and describes the batch shape. While it doesn't explicitly name alternatives or exclusion criteria, the contrast with list tools is implied.

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 significant behavioral context: it documents that Pluggy does not return a paid/status field, explains the nuanced meaning of payments[] (typically reflects previous bill payment), and describes the response shape as batch with { results, errors }. This prevents misinterpretation and sets accurate expectations.

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 moderately long but well-structured: it starts with the core purpose, then delimits what it does not do, followed by usage instructions and important notes. Each paragraph adds value without redundancy. Some slight verbosity (e.g., repeating 'bill-level detail' twice) could be trimmed, 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 no output schema, the description provides a thorough overview of the response structure (financeCharges, payments with fields, batch shape {results, errors}), critical behavioral nuances (paid/status absence, payments[] interpretation), and explicit guidance on prerequisite tools. This covers all essential aspects a user needs to correctly call and understand this tool.

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

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

The sole parameter bill_ids is an array of strings. The description adds meaning by explaining that IDs come from openfinance_list_credit_card_bills and that bill_ids should be passed as an array. Though schema coverage is 0%, the description effectively tells the user how to source the parameter value. It could be slightly more explicit about the exact format, but the guidance is sufficient.

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 bill-level detail for credit card bills by ID, specifying the exact fields (financeCharges, payments). It distinguishes from sibling tools by stating what it does NOT return (individual transactions) and directing to openfinance_list_transactions for that purpose. The verb 'returns' and resource 'bill-level detail' are precise.

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 (to get bill-level detail after discovering IDs via openfinance_list_credit_card_bills) and when not to (for itemized transactions, use openfinance_list_transactions). It also provides a critical caveat about interpreting payments[] in Brazilian Open Finance, preventing misuse. Instructions are clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is clearly safe and idempotent. The description adds behavioral details: return data includes executionStatus and connector metadata, and the all-case returns `{ count, items }`. No contradictions; the description enhances understanding 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 two sentences, front-loaded with the main purpose, then concise details on parameter behavior. No redundant or extraneous 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?

Given the single parameter and no output schema, the description covers the essential behavior. It mentions return format for the all-case but omits exact structure of the single-bank response. However, for a simple status check, it is sufficiently complete for an AI 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?

The input schema has only one parameter 'item' with no description (0% schema coverage). The description compensates by explaining the semantic difference: omitting it returns all banks, passing it returns one bank. This adds meaningful guidance beyond the schema.

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

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

The description clearly states the tool returns the current status of a bank connection with specific statuses (UPDATED, UPDATING, LOGIN_ERROR, etc.), executionStatus, and connector metadata. It distinguishes between retrieving status for all linked banks (omit item) or a single bank (pass item), which sets it apart from siblings like openfinance_list_connections that likely list connections rather than statuses.

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 two usage modalities: omit `item` for all banks or pass `item` for a single bank, providing clear context on when to use each. However, it lacks explicit guidance on when not to use this tool versus alternatives like openfinance_list_connections, but the implied distinction 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 the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: the distinction between `name` and `bank`, the connector-dependent nature of credit balance, and the structure of the response (aggregated vs single item). 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 relatively long but every sentence adds value, and it is well-structured: first the basic purpose, then special notes. It could be slightly more concise without losing information, but it is not overly verbose.

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

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

Given the complexity of the tool (two behaviors based on `item`, credit balance nuance, reference to another tool), the description is very complete. It covers return values, parameter effects, and caveats, leaving no major gaps despite lacking an output schema.

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

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

Despite 0% schema description coverage, the description fully compensates by explaining the effect of each parameter: omitting `item` lists all accounts, passing `item` targets a single bank; `type` filters by account type. It adds meaning far 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 it returns accounts for a bank connection with specific fields (BANK/CREDIT, balance, type, etc.). It distinguishes between the two account types and explains the role of `item` parameter, making the purpose highly specific and differentiated 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 explicitly explains when to omit `item` (to list all accounts across banks) and when to pass `item` (to target a single bank). It also provides guidance on the meaning of credit balance and directs to another tool for standardized amounts, offering clear when-to-use and when-not-to-use instructions.

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; description adds value by noting caching and single aggregated response (no batch ids), exceeding annotation coverage.

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

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

Three sentences, each concise and informative. Front-loaded with main purpose, 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?

No output schema, but description comprehensively lists response fields and notes caching and single-response nature. Adequate for a zero-parameter read-only tool.

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

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

Input schema has zero parameters (100% coverage), so baseline is 4. Description adds no param info but explains response fields (id, description, etc.), which is useful beyond schema.

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

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

The description clearly states the tool returns Pluggy's transaction category taxonomy, specifying the verb 'returns', the resource 'category taxonomy', and includes details about caching and field descriptions, distinguishing it from list tools for accounts/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 implicitly suggests use when needing category IDs for openfinance_update_transaction_category, but lacks explicit when-to-use/when-not-to-use guidance or alternatives among sibling 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 and idempotentHint, and the description adds context by specifying the returned fields and scoping to 'this install', which is beyond the annotations.

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

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

A single sentence that is front-loaded with the action and resource, containing 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?

For a zero-parameter, read-only tool with no output schema, the description adequately lists all return fields and scoping, making it 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?

No parameters exist, so schema coverage is 100%. Baseline is 4 as per rubric; description adds no parameter info, but none is needed.

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

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

The description clearly states the tool returns saved bank connections and lists specific fields (connector_id, item_id, bank name, add_connection_url). It distinguishes from other list tools by focusing on connections, making purpose unambiguous.

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

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

Usage is implied by the name and description as the tool for listing saved connections, but no explicit guidance on when to use vs alternatives (e.g., openfinance_list_accounts) 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?

Adds extensive behavioral details beyond annotations: payment assignment logic, derived payment_status, connector asymmetry, bulk support, warning for missing product. Annotations only provide readOnlyHint/idempotentHint/destructiveHint; description greatly enriches 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?

Very long and detailed, but structured in sections (closed bills, payment semantics, open bill, connector asymmetry, bulk). Could be more concise; some redundancy in explaining derived status. Length is justified by complexity but impacts 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?

No output schema exists, so description fully explains return values: fields, payments[], payment_status, open_bill, future_bills[], error handling. Covers all aspects of a complex tool with 5 parameters and multiple edge cases.

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 compensates partially. Explains include_open_bill (opt-in, cost) and account_ids (bulk support). Does not detail page, page_size, or account_id format. Lacks some parameter specificity.

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, lists key fields, and distinguishes from sibling tools like openfinance_get_credit_card_bill and openfinance_list_transactions.

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

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

Provides explicit guidance on when to use (closed bills) and when not (itemized transactions, pointing to alternative). Also explains the open_bill opt-in and warns against using balance. However, doesn't explicitly list all sibling differentiators.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds value by detailing the return structure on errors and listing specific data fields (balance, amount, dueDate, etc.), providing context beyond annotations. 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 informative and front-loaded with the main purpose. It could be more concise (e.g., omitting the list of fields), but it's not overly verbose and 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?

With no output schema and no parameter explanations, the description is incomplete. It covers the output reasonably well but fails entirely on input parameters, which are essential for agent invocations.

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 4 parameters (item, page, type, page_size) with 0% description coverage. The description does not explain any of these parameters, leaving the agent with no guidance on how to use them. This is a critical 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?

Clearly states what the tool does: returns investment portfolio for a connection, enumerating specific asset types (FIIs, stocks, ETFs, etc.) and the data fields returned. Verb 'returns' and resource 'investment portfolio' are specific. Distinguishes from sibling tools like list_accounts by focusing on 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?

Provides some context about error handling (returns structured response on 403) but does not explicitly state when to use this tool vs alternatives like openfinance_list_accounts or openfinance_list_transactions. Usage is implied by the purpose but lacks exclusion criteria.

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, so the description's job is to add context. It adds details about returned fields (quantity, value, netAmount, agreedRate, expenses) and bulk support via investment_ids, which is valuable beyond annotations. However, it does not mention pagination behavior or rate limits.

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

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

The description is concise with two short paragraphs: the first describes the output and fields, the second gives usage guidance. Every sentence adds value, no redundancy.

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

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

The tool has 4 parameters, no output schema, and is moderately complex. The description covers the core output well but fails to document page and page_size parameters. For a tool without an output schema, the description should explain what is returned, which it does, but the missing pagination details reduce completeness.

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

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

The input schema has 0% description coverage, so the description must compensate. It clarifies investment_id (implied by context) and mentions investment_ids for batch execution, but omits page and page_size entirely. The description adds partial meaning but leaves two parameters undocumented.

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

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

The description clearly states the tool returns movement history for a specific investment position, listing transaction types (BUY/SELL/TAX/etc.) and specific fields. It distinguishes itself from siblings like openfinance_list_investments by focusing on transactions for a given investment, and from openfinance_list_transactions by being investment-specific.

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

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

The description explicitly says 'Use after openfinance_list_investments to get the investment_id,' providing a clear prerequisite and sequence. It implies when to use this tool, but does not mention when not to use or compare directly to siblings like openfinance_list_transactions_by_item.

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 behavioral details beyond annotations: multiple connections queried sequentially with rate-limit spacing, return format {results, errors}. Annotations indicate read-only, idempotent, non-destructive, which description does not contradict.

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 purpose and endpoint, no redundant information. Efficient 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?

Given no output schema and low schema coverage, description provides complete context for usage: parameter format, sequential behavior, return structure. Sufficient for a listing 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 0% but description fully compensates: explains items format (connection selectors) and effect of omitting. Adds meaning that schema alone lacks.

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

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

Description clearly states it lists loan contracts per bank connection, specifying the endpoint and parameter behavior. It distinguishes from sibling tools by being loan-specific.

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 context on when to use (list loans per connection) and how to use (omit items for all banks). Lacks explicit mention of when not to use or direct alternatives, but sufficient for a focused 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses detailed behavioral traits: PENDING vs POSTED variation by bank, search aggregation up to 5000 transactions, error handling (returns warning/error instead of throwing), token cost and coverage variation for different detail levels, and the linkage of credit card transactions to bills via billId. 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 lengthy but well-structured: it opens with the core purpose, then addresses credit card specifics, followed by filtering, pagination, search, error handling, detail parameter, and related tools. While a few sentences could be tightened (e.g., repeated mention of bank variation), the verbosity is justified by the tool's complexity and the detail needed for correct use.

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

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

The description covers all essential aspects: tool scope, account type differences, integration with sibling tools (openfinance_list_credit_card_bills, openfinance_list_accounts, openfinance_get_item_status), parameter details, error handling, pagination limits, and bulk execution. No output schema is provided, but the description mentions key return fields (total, results, warning, error, truncated). For a tool with 8 parameters and complex behaviors, this is exceptionally 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?

Despite 0% schema coverage, the description fully explains all 8 parameters: date format for from/to, pagination size (max 500), three detail options (compact/rich/raw) with use cases and trade-offs, search_queries behavior (case-insensitive, OR semantics, aggregation limit), and bulk support via account_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 starts by stating it returns transactions for bank accounts (BANK or CREDIT type), clearly identifying the tool's main function. It further distinguishes its role for credit cards as the ONLY way to get itemized transactions, and names a sibling tool (openfinance_list_credit_card_bills) for bill totals, showing how it differs.

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: for CREDIT accounts it's the only source for itemized transactions, and it contrasts with openfinance_list_credit_card_bills for bill totals. It advises narrowing date ranges if truncated:true is returned, and recommends checking connection health via openfinance_get_item_status when total is 0. It also explains when to use different detail levels and mentions bulk support.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details: internal account resolution, data structure for monthly granularity (compact summary with por_mes, top_despesas, by_account), truncation cap at 5000/account with truncated flag, and behavior of detail and granularity modes. 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 lengthy but efficient—every sentence adds value. It front-loads the core purpose and then systematically covers all parameters, use cases, and edge cases (truncation). Slightly verbose due to Portuguese keywords and examples, but still well-structured and not wasteful.

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

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

Given 0% schema coverage and no output schema, the description provides complete context: it lists all parameters with semantics, explains return format (summary breakdown, per-account, top lists), mentions truncation behavior, and gives examples of use cases. No gaps for an agent to infer incorrectly.

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

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

Schema coverage is 0%, but the description fully explains all 7 parameters: from/to (ISO dates), item (connector_id/name or item_id, can omit), type (BANK/CREDIT), granularity (monthly/raw with defaults), detail (compact/rich/raw), and top_n (implied by top lists). Enum values are described with concrete behaviors, fully compensating 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 it's a consolidated cash-flow analysis for a bank connection over a period, resolving accounts internally. It uses specific verbs and resource ('cash-flow analysis', 'whole bank CONNECTION') and distinguishes from siblings by noting it avoids separate account listing calls and returns summary vs raw 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?

Explicitly tells when to use (for annual/monthly analysis, cash flow, top expenses/revenues) and when not (if raw rows needed, can set granularity to raw but warns it's heavier). It advises omitting item to analyze all banks and notes not needing to call openfinance_list_accounts first, providing clear context for 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 declare readOnlyHint and idempotentHint. Description adds transparency about checking a public status page, returning specific data like incidents affecting connected banks, and that it's non-destructive.

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 informative but slightly lengthy; however, every sentence adds value and purpose is 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, description covers return fields and usage context well. Provides enough detail for an agent to understand what the tool returns and how to interpret it.

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 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?

Clearly states it checks the LIVE operational status of the Open Finance provider's public status page, differentiates from openfinance_get_item_status, and specifies what it returns (global indicator, degraded components, incidents, your_banks_affected).

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

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

Explicitly says when to use it: when data looks incomplete/stale despite updated connection. Distinguishes from connection-level status tool and explains it helps differentiate 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that the tool honors the user's plan (hides PJ banks for PF plans) and returns a hint without keywords, which are useful behavioral details beyond the annotations.

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

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

The description is well-structured and front-loaded, with each sentence adding value. It is slightly verbose but remains clear and focused. Minor redundancy could be trimmed.

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

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

Given no output schema, the description covers return fields and behavior. It explains the key aspects needed for an agent to use the tool effectively, though it omits error handling and pagination details.

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 that keywords[] is required (though schema doesn't mark it required) and what it does, and that include_accounts triggers account inclusion. This adds semantic meaning beyond the raw schema.

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

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

The description clearly states the tool searches bank connectors by name using a keywords array, and specifies the return information including connector id, access type, audience, linked connections/accounts, and a connect_url. It distinguishes itself from dumping the whole catalog by requiring keywords.

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 instructs to call this tool before connecting to provide a one-click link, and notes that omitting keywords returns a hint rather than the full catalog. It implies when to use but does not explicitly contrast with sibling tools 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?

Discloses side effect of creating a Category Rule, which teaches Pluggy for future transactions. Describes batch behavior with per-item errors not failing the whole batch. Annotations are readOnlyHint=false, destructiveHint=false, and description adds crucial mutation details beyond that.

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

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

Single paragraph is dense but each sentence adds value: action, parameters, side effect, batch behavior. No redundancy; front-loaded with primary 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?

Covers all aspects: what it does, how to call it, what to pass, what side effects occur, what response looks like. No output schema exists, but description provides the necessary structure. No gaps remain.

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 fully compensates: explains items array structure, required fields, and sources for transaction_id and category_id. Also provides batch response shape, including the updated, results, and errors 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?

Starts with clear verb 'Corrects' and resource 'category of one or more transactions' (PATCH /transactions/:id). References specific sibling tools for parameter sources, distinguishing this corrective action from listing or category 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?

Explicitly states when to use: 'to fix miscategorized transactions and improve categorization accuracy going forward.' Provides clear prerequisites (transaction_id from openfinance_list_transactions, category_id from openfinance_list_categories) and explains consequences (overrides auto-categorization, creates Category Rule).

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 the tool is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description does not add behavioral details beyond that, and idempotency is hinted but not explained.

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 with only two sentences, no redundant 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?

With no output schema and 0% parameter coverage, the description is insufficient. An agent needs to know what the 'message' field should contain (e.g., a summary), and whether 'context' is for description or environment. The tool's purpose is clear but parameter usage is vague.

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 mentions the 'conversation' parameter should contain recent messages, but does not describe the 'context' or 'message' parameters beyond implying the message is the bug report. This leaves the agent guessing.

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

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

The description clearly states it is for reporting bugs, missing features, or feedback. It uses a specific verb ('Report') and resource ('bug'), distinguishing it from sibling tools which are mostly 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?

The description tells the agent when to use the tool (for bugs, features, feedback) and gives a specific instruction to include the conversation array. It does not explicitly state when not to use it or alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's safety burden is low. The description adds the specific return content (versions), which is helpful beyond annotations. 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?

A single, clear sentence with no extraneous words. Perfectly concise for a simple info 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 zero parameters and no output schema, the description completely informs the agent about what the tool returns (versions). No gaps remain.

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

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

No parameters exist, so schema coverage is 100%. Baseline for zero-param tools is 4. The description does not need to add parameter information.

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

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

The description uses a specific verb 'Show' and resource 'current MCP platform and adapter versions.' It clearly states what the tool returns, distinguishing it from sibling tools like authenticate or openfinance 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?

No explicit guidance on when to use this tool vs alternatives, but given its trivial nature (version info) and distinct sibling tools, the implied usage is clear. A moderate score due to lack of explicit 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, providing a complete safety profile. Description adds the return content details but no behavioral traits beyond that.

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 clear sentence, no wasted words. Front-loaded with key action and resource.

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?

Tool has no parameters and no output schema, but description covers return content adequately. Annotations cover behavioral aspects. Complete for a simple status 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 present, so baseline is 4. Description adds value by specifying the returned data content beyond the schema.

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

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

Description clearly states the tool returns toolkit state, listing specific items (installed MCPs, connection status, catalog tool counts). Uses strong verb 'Returns' and specific resource, distinguishing it from sibling tools which focus on individual 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?

Implied usage as a status or diagnostic tool, but no explicit when-to-use or alternatives. With many sibling tools, explicit guidance would help, but context makes it somewhat clear.

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