99Pay MCP

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

Describes behavioral traits beyond annotations: calling with token sets a session, without gives a link. Explains non-expiring vs session nature, adding context not in annotations.

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

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

Description is informative and front-loaded, but slightly verbose. Each sentence adds value, though a bit more conciseness could improve.

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 both authentication flows (permanent config and session token), explains parameter usage, and no output schema needed. Complete for a simple auth tool.

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

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

With 0% schema coverage, description compensates by explaining the 'token' parameter's meaning and usage. Could add format specification but 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?

Clearly states the tool's purpose: handling authentication for MCP.AI in IDE agents. Distinguishes itself from siblings (no other authentication tools).

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

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

Explicitly describes when to use the tool: to get a login link or to set a token for session login. Provides clear guidance on the preferred permanent config method vs session-only paste.

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 behavioral context about returning different outputs based on connection state (authenticated:true vs connect_url). This goes beyond annotations, though it could mention that repeated calls are safe.

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, no wasted words. Perfectly concise for the complexity.

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

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

Despite no output schema, the description fully explains returned values and the two possible states. Covers all needed information for a zero-parameter tool.

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

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

No parameters exist, so schema coverage is 100%. Baseline for 0 parameters is 4, and the description does not need to add parameter info. No missing 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?

Description clearly states it returns connection status and URLs, with specific details about the two scenarios (authenticated vs missing credentials). This distinguishes it from sibling tools like 'authenticate' which handles credential submission.

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

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

The description implies usage for checking connection status but does not explicitly state when to use it over alternative tools. It lacks guidance on context (e.g., 'call before authenticate to verify state') or when not to use it, so barely meets implied usage.

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

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

The description fully compensates for the lack of rich annotations by detailing behavioral traits: invoke runs tools one-off without installation, may return connect/checkout links for auth or payment, and writes (install/uninstall/subscribe/cancel) require workspace owner/admin. No contradiction with annotations exists.

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 dense paragraph that packs substantial information without significant redundancy. It is front-loaded with the key identification. However, it could be more structured (e.g., using bullets) to improve readability without losing 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 tool's complexity (13 parameters, multiple actions, no output schema), the description covers the primary flow and key behavioral aspects well. However, it omits details on output format and leaves several parameters unaddressed, which creates gaps for an agent to fully understand the tool's capabilities.

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 for 13 parameters, the description only indirectly explains a few key parameters (action, mcp_id, tool_id, arguments) by describing actions. It fails to document many parameters like limit, immediate, tier_slug, conversation, request_name, report_context, and request_details, leaving the agent without meaning 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 clearly states it is the official marketplace for MCP discovery and execution, with explicit verb+resource ('THE official mcp.ai marketplace'). It distinguishes itself from sibling tools by positioning itself as the primary tool for searching, describing, and invoking MCPs, while siblings like authenticate and openfinance tools handle specific domains.

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

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

The description provides explicit guidance on when to use this tool ('use THIS tool FIRST'), outlines the core flow (search → describe → invoke), and contrasts invoke vs. install with clear recommendations. It also mentions when to use other tools like list_tools, report_bug, and request_mcp, making the usage boundaries very clear.

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

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

The description adds behavioral context beyond the destructiveHint annotation by stating that consent is revoked, connection data is deleted, data becomes unavailable, and a re-connect URL is returned. This is consistent with the annotation and adds value.

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 concise sentences that front-load the main action. Every sentence adds 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?

For a simple tool with one parameter and no output schema, the description covers the action, consequence, and return value. However, it lacks parameter clarification and error conditions, making it adequate but not fully complete.

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

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

The input schema has 0% coverage and the description does not explain the 'item' parameter. With only one parameter and no schema description, the tool description fails to provide any meaning for it, which is a significant 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 revokes consent and deletes connection data, and mentions the return of a re-connect URL. The verb 'revokes' and resource 'Open Finance consent for a specific bank' are specific, and it distinguishes from siblings like 'connect' or '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 usage when needing to disconnect a bank, but lacks explicit guidance on when to use this tool versus alternatives like 'openfinance_force_sync' or 'openfinance_get_item_status'. No exclusions or alternative suggestions are 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?

Discloses key behaviors: waits up to ~60s, polls until done, returns results/errors, status fields like 'needs_action' and 'timed_out'. No contradictions with annotations (readOnlyHint=false, destructiveHint=false).

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

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

Well-structured, front-loaded with action and usage. Every sentence adds value, though slightly verbose with multiple details. Could be tightened but still effective.

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

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

Comprehensively covers return format ('results, errors'), status fields, error conditions, and timeout behavior. No output schema, so description fully compensates. Also references sibling tool for follow-up.

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?

Explains both parameters: 'items' as array of selectors or omitted for all; 'wait' as fire-and-forget when false. Compensates for 0% schema coverage with detailed usage.

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

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

Clearly states the tool forces bank re-sync and waits. Distinguishes from siblings like openfinance_get_item_status (re-check after timeout) and openfinance_list_connections (listing).

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 (stale balance/transactions) and what it does (pulls fresh data without disconnecting). Implicitly provides alternative (use openfinance_get_item_status after timeout). Lacks explicit 'when not to use' but sufficient 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=true and destructiveHint=false. The description adds value by detailing real-time behavior, array size limits, specific error handling for credit accounts, and structured warnings instead of exceptions, enriching the agent's 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 concise (three sentences and a response shape), front-loading the purpose and then adding constraints, error handling, and output format. No extraneous information; every sentence contributes essential details.

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

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

For a simple tool with one required parameter and no output schema, the description covers input constraints, error behavior, and response structure. It clarifies that errors are separate from results. A brief mention of what the results array contains would improve completeness, but it's largely sufficient.

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

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

The schema has 0% description coverage with a single parameter (account_ids). The description adds critical semantic information: 'Pass account_ids as an array (1–50)', which constrains the size and format beyond the bare schema, fully compensating for the lack of schema descriptions.

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 REST endpoint, specifying the verb and resource. It distinguishes from sibling tools like openfinance_list_accounts by focusing on balance data for specific account IDs.

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 usage constraints (array of 1-50 account_ids) and error handling guidance for credit accounts (BALANCE_FETCH_ERROR with warnings). However, it does not explicitly compare to alternative tools or state when to use this versus other balance-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 already convey safety profile; description adds batch shape and array limit 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 covering purpose, parameter format, and output shape with no fluff.

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

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

Sufficient for a simple read-only tool; describes output shape and parameter constraints, though no further details on possible errors.

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 adds crucial constraints (array size 1–50) and batch behavior, going beyond the bare schema.

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

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

The description clearly states the tool returns full account objects with extended creditData, specifies the endpoint, and distinguishes from list tools by requiring specific IDs.

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 over sibling tools like openfinance_list_accounts, nor any prerequisites or exclusions.

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), description adds batch shape { results, errors }, notes Pluggy does not return a paid/status field, and clarifies payments[] semantics (payments during this bill's cycle typically for previous bill). No contradiction with annotations.

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

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

Description is fairly long but every sentence adds value: purpose, exclusions, alternatives, usage instructions, caveats. Front-loaded with main function, well-organized. Slightly verbose but not wasteful.

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

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

Given only 1 parameter and no output schema, description is highly complete: covers return shape, alternative tools, edge cases (paid status), behavioral quirks, and typical usage flow. Leaves no major gaps for an AI 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?

With 0% schema description coverage, description adds meaning by explaining to pass an array, how to get IDs via another tool, and the batch shape. Provides practical usage context beyond schema names.

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 bill-level detail for credit card bills by id, listing specific fields (financeCharges, payments[] with subfields). It also explicitly states what it does NOT return (individual transactions) and points to openfinance_list_transactions, distinguishing it from related 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?

Provides explicit guidance: use openfinance_list_credit_card_bills first to discover ids, pass bill_ids as an array, and for itemized transactions use openfinance_list_transactions. Also explains the cross-bill logic for checking payment status, offering a clear alternative.

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 read-only, idempotent, and non-destructive. The description adds moderate value by detailing the return fields (status, executionStatus, connector metadata) and the array behavior when omitting 'item'. However, it does not disclose authentication requirements or rate limits, but annotations cover the core behavioral traits.

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 unnecessary words. It front-loads the purpose and efficiently covers the parameter behavior and return format. 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 tool's simplicity (one optional parameter, no output schema, and annotations covering safety), the description provides sufficient information for an AI agent to select and invoke it correctly. It covers the main behavior and parameter nuances without needing additional 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?

The input schema has a single optional 'item' parameter with 0% schema description coverage. The description fully compensates by explaining its function: pass it for a single bank, omit for all banks, and describes the corresponding return structure. This adds essential meaning beyond the raw schema.

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

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

The description explicitly states it returns the current status of a bank connection, listing specific status values (UPDATED, UPDATING, LOGIN_ERROR), executionStatus, and connector metadata. It clearly distinguishes between getting all banks (omit 'item') vs a single bank (pass 'item'), setting it apart from siblings that may list connections or 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 guidance on when to omit or include the 'item' parameter, with distinct return structures for each case. It does not explicitly exclude scenarios or mention alternatives, but siblings like 'openfinance_list_connections' have different purposes, so the usage context is sufficiently 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 indicate read-only and idempotent behavior, which the description reinforces. It adds significant context about field meanings (e.g., 'bank' vs. 'name', credit balance dependency) and aggregation behavior, 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?

The description is detailed but front-loaded with the core purpose. Some sentences could be tightened, but overall it is well-structured and every sentence adds value given the complexity of the tool's 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?

Without an output schema, the description adequately covers return fields, aggregation behavior, and important caveats about credit balance. It is complete for a read-only list tool with two optional parameters.

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

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

Despite zero schema description coverage, the description fully explains both parameters: 'item' for targeting a bank or omitting for all, and 'type' with enum values BANK and CREDIT. This compensates completely for the schema's lack of documentation.

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

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

The description clearly states the tool returns accounts for a bank connection, listing specific fields like balance, number, type, etc. It also distinguishes from sibling tools by mentioning alternatives like openfinance_list_credit_card_bills for standardized bill amounts.

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

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

Explicit guidance is provided: when to omit 'item' to list all accounts, when to pass 'item' for a single bank, and a warning about the credit balance meaning. It also directs users to an alternative tool for standardized billing amounts.

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

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

The description adds value beyond annotations by disclosing that the response is cached for the adapter session, single aggregated response, and no batch ids. Annotations already mark it as read-only and idempotent, and the description confirms non-destructive 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?

The description is concise, with a clear first sentence stating the core function. Every sentence adds relevant information: caching, field details, and response aggregation. No redundant 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?

Despite lacking an output schema, the description thoroughly explains the returned fields (id, description, descriptionTranslated, parentId, parentDescription) and notes the caching and single-response nature. This is complete for a parameterless 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?

There are no parameters, and schema description coverage is 100%. Per the guidelines, the baseline score for zero parameters is 4, and the description does not need to add 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 that the tool returns Pluggy's transaction category taxonomy, cached for the adapter session. It distinguishes itself from sibling tools by being the only category list tool, and the title 'List Transaction Categories' reinforces the purpose.

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

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

The description implies usage for obtaining categories, especially the id used by openfinance_update_transaction_category. However, it does not explicitly state when to use it vs alternatives or when not to use it, though no alternative category tools exist.

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

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

Annotations already mark it as read-only and idempotent. The description adds context about returned fields and an add_connection_url but does not disclose additional behavioral traits like rate limits, data freshness, or connection status semantics.

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

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

Single sentence, front-loaded with the main purpose, no wasted words.

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

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

No output schema, but description explains return values adequately. Could mention if the list is paginated or sorted, but given the simple nature, this is sufficient.

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

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

Input schema has zero parameters and 100% coverage, so the description does not need to add parameter meaning. Baseline 4 is appropriate.

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

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

The description clearly states the verb ('returns') and the resource ('saved bank connections'), lists specific returned fields, and distinguishes it from sibling 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. While the purpose is clear, there is no mention of prerequisites, when not to use it, or how it differs from sibling tools like openfinance_get_item_status or 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?

The description goes far beyond the read-only annotations by detailing complex payment semantics (payment_date cycle logic, cross-bill derivation for payment_status), connector-specific limitations (open bill availability), and behavioral notes like opt-in requiring extra scans. It also warns against assuming payment status from non-empty payments[]. All disclosed traits add value beyond annotations.

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

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

The description is long but well-structured: it starts with a clear summary, then breaks down key points (payment_status, open_bill, connector asymmetry, bulk support). It front-loads the main purpose and uses new lines for logical sections. However, some sentences are dense and could be simplified for 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?

Given the absence of output schema and the tool's complexity (Brazilian Open Finance semantics, derived fields, connector variance), the description is remarkably complete. It covers return fields, derived payment_status, open bill logic, cross-tool references, and failure modes. No critical behavioral aspect is omitted.

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

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

The schema has 0% description coverage, so the description must compensate. It explains include_open_bill and account_ids (bulk support), but does not describe page and page_size, which are common but still parameters. The description adds value for non-obvious parameters but misses simple ones, leaving a gap for new users.

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 the tool returns CLOSED credit card bills for a CREDIT-type account, lists key fields (dueDate, totalAmount, payments[], payment_status, etc.), and distinguishes itself from sibling tools by noting that itemized transactions require openfinance_list_transactions. The verb 'list' and resource 'credit card bills' are clear and 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 provides explicit guidance on when to use this tool (for closed bill summaries), when not to (for itemized purchases, refer to openfinance_list_transactions), and clarifies the derived payment_status logic to avoid misinterpretation. It also explains the opt-in include_open_bill parameter and connector asymmetry. However, it does not explicitly contrast with the sibling openfinance_get_credit_card_bill, which weakens the completeness slightly.

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 key behavioral details: returns a specific error object on 403, and lists available fields in the portfolio. No contradictions.

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

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

Description is fairly concise for the amount of detail given, though could be more structured with separate parameter and return sections.

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

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

Good return field info but lacks parameter guidance; no output schema, so completeness is hampered. Adequate for a read-only list tool but missing input 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?

With 0% schema description coverage, the description fails to explain the 4 parameters (item, page, type, page_size). It only lists return fields, not input 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?

Description explicitly states the tool returns investment portfolio for a connection with specific asset types, clearly distinguishing it from siblings like openfinance_list_investment_transactions.

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

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

Describes when to use (connection with INVESTMENTS enabled) and error handling (returns structure instead of throwing), but doesn't explicitly mention when not to use or 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, destructiveHint. Description adds value by detailing return fields, transaction types, and bulk support, 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 paragraphs with front-loaded main purpose. No wasted words, but could be more structured with parameter explanations.

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 return data and prerequisite well, but lacks pagination parameter details and does not explain required vs optional parameters. Adequate but not fully complete.

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

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

Schema description coverage is 0%, so description must compensate. Only mentions bulk support via investment_ids, but does not explain page, page_size, or the distinction between investment_id and investment_ids. Missing parameter details.

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

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

The description clearly states the tool returns movement history for a specific investment position, listing transaction types and data fields. It distinguishes itself from sibling tools like openfinance_list_transactions by specifying investment context.

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

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

Explicitly instructs to use after openfinance_list_investments to obtain investment_id, providing a clear prerequisite. Does not explicitly mention when to use alternative tools, but context is sufficiently clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral details: sequential queries with rate-limit spacing, per-connection results and errors. No contradictions.

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

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

The description is three sentences, front-loaded with the core purpose, and delivers all necessary 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?

Despite no output schema, the description mentions the return format ('{ results, errors }'). It lacks details on the loan object structure, but the annotations cover safety. For a list tool, this is fairly 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 no descriptions (0% coverage), so the description must compensate. It fully explains the 'items' parameter: an array of connection selectors with format details, and the two modes of use. This adds significant meaning beyond the schema.

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

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

The description clearly states it lists loan contracts per bank connection, using a specific verb and resource. It distinguishes from sibling list tools by specifying loans. The mention of the endpoint further clarifies purpose.

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

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

The description explains two usage modes: with 'items' for specific connections, and omitting 'items' for all banks. It also mentions sequential querying with rate-limit spacing, which informs usage. However, it does not explicitly compare to other list tools or state when to prefer this one.

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 discloses crucial behaviors: variability of PENDING/POSTED across banks, aggregation behavior with search_queries (up to 5000 before filtering), error handling (warning/error instead of throwing), and the truncation indicator. These details significantly supplement 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 lengthy but well-structured with clear sections: main purpose, CREDIT-specific behavior, filtering details, bulk support. It front-loads the core function and all sentences add value. However, it could be slightly more concise without losing information, e.g., grouping some conditional behaviors.

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, many siblings), the description covers all essential aspects: purpose, parameter details, usage guidelines, error handling, alternative tools, and edge cases like PENDING/POSTED and truncation. It is self-contained and equips the agent to use the tool correctly without needing to infer missing 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 fully compensates: explains from/to as ISO YYYY-MM-DD, pagination with max 500/page, search_queries as case-insensitive substring match with OR semantics, account_ids for bulk, and notes that search_queries aggregates up to 5000 transactions. This is comprehensive and adds meaning beyond the schema.

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

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

The description explicitly states 'Returns transactions for a bank account (BANK or CREDIT type)', clearly identifying the verb (returns) and resource (transactions) with specific account types. It distinguishes from sibling tool openfinance_list_credit_card_bills by noting it deals with credit card bills while this tool handles itemized 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 provides extensive guidance: when to use for CREDIT accounts (only way for itemized transactions), how it relates to bills, when to use openfinance_list_credit_card_bills instead, and instructions for handling search_queries (narrow from/to if truncated). It also advises checking connection health if total=0, directing to openfinance_get_item_status and openfinance_force_sync.

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, indicating a safe read. The description adds valuable behavioral details: internal account resolution, fan-out of transactions, capping at 5000 per account with truncation flag, and the compact vs raw output structure. 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 comprehensive and well-structured, with the core purpose front-loaded. Every sentence adds value, but it could be slightly more concise (e.g., combining some repetition about granularity). Still, it's efficient given the tool's complexity.

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

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

Given the tool's complexity (6 parameters, no output schema, 0% schema coverage), the description covers all necessary aspects: aggregation behavior, output structure (compact vs raw), truncation, filtering, and use cases. It adequately distinguishes this tool from 24 siblings, making it easy for an AI to select 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?

Despite 0% schema description coverage, the description thoroughly explains all six parameters: 'item' (target one bank or omit for all), 'from'/'to' (ISO date format), 'granularity' (monthly vs raw), 'type' (filter BANK/CREDIT), and 'top_n' (implied for top expenses). This adds essential meaning beyond the raw schema.

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

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

The description starts with a specific verb ('Consolidated cash-flow analysis') and resource ('whole bank CONNECTION'), distinguishing it from sibling tools that list individual transactions per account. It explicitly states it resolves accounts internally, avoiding the need for 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?

Clearly explains when to use the tool: for 'análise anual/mensal', 'fluxo de caixa', etc. Provides explicit guidance on omitting 'item' to analyze all banks, and when to set 'granularity' to 'raw'. Contrasts with alternatives like calling openfinance_list_accounts first.

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, destructiveHint. Description adds what it returns: global indicator, degraded components, open incidents, and flags for your 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?

Single paragraph but front-loaded with purpose. Could be slightly more concise, 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 no parameters or output schema, the description is highly complete: explains what it returns, when to use, and distinguishes from siblings.

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 (100% schema coverage), baseline is 4. The description adds no param information but explains the output and usage, which 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?

Specifically states it checks the LIVE operational status of the Open Finance provider (public status page). Clearly distinguishes from related tools like openfinance_get_item_status, which is about your connection's status.

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

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

Explicitly tells when to use: when data looks incomplete/stale even though connection shows UPDATED. Contrasts with openfinance_get_item_status and suggests using it to diagnose provider-side problems.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds user-plan filtering and no catalog dump behavior without keywords. Contradictions: none.

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?

Five sentences, front-loaded with purpose and key details. No redundant information; each sentence serves a purpose. Slightly verbose but still concise.

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

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

Covers parameters, return fields (id, access, audience, connections, connect_url), and plan-aware behavior. Lacks output format details but acceptable for a search tool without 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?

Schema has 0% description coverage, so description must compensate. It explains keywords as array of names (with example) and include_accounts for returning accounts. This adds sufficient meaning beyond schema.

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

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

The description clearly states the tool searches bank connectors by name, with specific verb 'searches' and resource 'bank connectors'. It distinguishes from sibling tools by focusing on search and pre-connection linking.

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 'Call this BEFORE connecting' and notes keywords are required, returning a hint otherwise. Lacks explicit when-not-to-use or alternative tools, but context is clear.

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

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

Beyond annotations, describes the side effect of creating a Category Rule and the batch error handling. Discloses that it overrides automatic categorization and teaches Pluggy, which is critical behavioral information.

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

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

A single dense paragraph that could benefit from structure (e.g., bullet points or separate sentences), but it is front-loaded with the primary action and essential details.

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

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

Covers main functionality, side effects, and error handling. Could be enhanced by noting edge cases (e.g., empty items) or clarifying that the rule applies case-insensitively to future similar transactions.

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 specifying the structure of 'items' and how to source transaction_id and category_id. Also describes the batch response shape.

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

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

Clearly states the verb ('Corrects the category'), resource ('one or more transactions'), and includes the HTTP method and endpoint. Distinguishes from sibling tools that list or get 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?

Explains when to use (fix miscategorized transactions) and provides context for obtaining required IDs from sibling tools. Lacks explicit 'when not to use' but gives 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 indicate idempotency and non-destructiveness. The description adds context about including conversation for reproduction, but does not detail other behavioral aspects like whether feedback is stored or sent. It neither contradicts nor significantly enhances the annotations.

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

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

The description is a single, efficient sentence with no wasted words. It is front-loaded with the purpose and includes an important usage note.

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 three-parameter schema with no output schema, the description is incomplete. It explains only one parameter and lacks details on input formats, expected behavior, or return value. The tool is simple, but the description under-serves an agent's need for complete understanding.

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

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

With 0% schema description coverage, the description must explain all parameters. It only clarifies the 'conversation' parameter as requiring recent messages for reproduction, but does not explain 'message' (required) or 'context'. This leaves significant gaps for an 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's purpose: reporting bugs, missing features, or sending feedback. It is a specific verb+resource combination that distinguishes it from sibling tools, which are largely finance-related 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 provides a usage hint ('Include the conversation array with recent messages for reproduction'), but does not explicitly state when to use this tool versus alternatives. Given the lack of similar sibling tools, the ambiguity is minimal, but explicit guidance is missing.

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 specify readOnlyHint=true and idempotentHint=true, so the description adds no additional behavioral context beyond stating what the tool shows. It 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?

Description is a single concise sentence that directly states the tool's purpose with no wasted words.

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

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

Given the tool's simplicity (no parameters, no output schema, annotations present), the description is fully adequate and leaves no gaps.

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

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

Tool has zero parameters and 100% schema coverage, so the baseline is 4. The description does not need to add parameter 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?

Description uses specific verb 'Show' and resource 'current MCP platform and adapter versions', clearly differentiating it from sibling tools which focus on authentication, financial data, or connectivity.

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 when/when-not or alternative guidance is given. Usage is implied for obtaining version info, but the description lacks explicit context on when to prefer this tool over others.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the output content but does not disclose additional behavioral traits such as side effects, authorization needs, or rate limits. Since annotations cover the safety profile, the description provides some added value but not significant.

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

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

The description is a single concise sentence that fronts the main action ('Returns the current toolkit state:') then lists specifics. Every word is necessary; 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?

Given no output schema, the description explains the return content (installed MCPs, connection status, catalog tools count), which is reasonably complete. It could provide more structural detail, but the essential information for an agent to understand the tool's result is present.

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 (0 params), so schema description coverage is 100% by default. Baseline is 4 for 0 params, and the description does not need to add parameter info. The description's mention of what is returned 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 the current toolkit state, specifying exactly what it includes (installed MCPs, connection status, catalog tools count). This is a specific verb+resource, and it distinguishes from sibling tools that perform actions rather than provide state information.

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

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

The description implies when to use this tool (to check toolkit state) and no alternatives are mentioned, but the context is clear given the naming and sibling tools which are all functional. It lacks explicit guidance on when not to use, but the straightforward nature makes it adequate.

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