Ágora MCP

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

Adds behavioral context beyond annotations: describes permanent vs session login; explains that no-arg call returns a link. Annotations indicate idempotent and non-destructive, which description aligns with.

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, front-loaded with target audience and purpose. Efficiently covers key info, though includes some procedural detail that could be streamlined.

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 use cases and parameter, but lacks explicit mention of error handling, token validation, or response format. For a 1-param tool with no output schema, description is adequate but incomplete.

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 optional token parameter, when to provide it (JWT from browser), and what happens if omitted. Adds meaning beyond schema definition.

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

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

Description clearly identifies the tool as authentication for IDE agents, specifying it handles login via browser and token. It distinguishes from siblings like 'connect' by explicitly mentioning 'MCP.AI for IDE agents (Cursor, etc.)'.

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 two usage scenarios: permanent config method and session-only token method. Tells when to call without args to get a link. Could be stronger by explicitly stating when not to use, but covers main cases.

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

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

Adds valuable details beyond annotations by explaining response structure (authenticated, pending, connect_url). Annotations already indicate read-only, idempotent, non-destructive; description aligns and enriches.

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 purpose. Every sentence provides 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?

Fully describes what the tool returns under different conditions. No missing aspects given simplicity and lack of 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?

No parameters present, so no additional information needed. Baseline scored at 4 as per guidelines for zero parameters.

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

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

Clearly states it returns connection status and URLs. Differentiates from sibling 'authenticate' by being a status check rather than performing authentication.

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

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

Provides specific conditions for different outputs (all connected vs missing credentials). While not explicitly stating when not to use, the context strongly implies usage for checking connection 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 indicate readOnlyHint=false and destructiveHint=false, and the description does not contradict them. It goes beyond annotations by disclosing key behavioral traits: invoke works even when the MCP is not installed, runs one-off without bloating the toolkit, returns connect/checkout links when credentials or payment are needed, and writes require workspace owner/admin. It also explains that search/describe flag installed_in_toolkit vs installed_in_workspace. This is substantial additional context about auth, side effects, and retry 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 information-dense and front-loaded with the core purpose and flow. It is a single long paragraph but each sentence adds value, with no filler. However, it could be better structured with bullets or explicit parameter/action lists to improve scannability. The length is justified by the tool's complexity (14 actions, 23 params), so it earns a 4 rather than lower.

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 (many actions, no output schema, many optional params), the description covers the primary flow, key behavioral nuances (one-off invoke, auth/payment links), and the distinction between invoke/install. It even explains the prompt library sub-feature. However, it omits a few actions like 'resume' and does not explain some params (immediate, tier_slug, conversation, etc.), leaving minor gaps. Overall, it is sufficiently complete for effective use in most scenarios.

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 carries the burden. It explains the core parameters: action=search/describe/invoke, mcp_id, tool_id, arguments, and prompt-related variables (prompt_body, prompt_vars, prompt_slug, etc.). It also maps each action to its intended input (e.g., request_mcp for requests, cancel_reason/cancel_comment for cancellation). However, it leaves several parameters unexplained (e.g., limit, immediate, tier_slug, conversation, message, report_context, request_details) without context, though the description gives enough to correctly invoke the primary workflow.

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

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

The description clearly states the tool's function: 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It specifies the resource (MCP/tool catalog) and the primary verb flow (search → describe → invoke), and distinguishes from sibling openfinance_* tools that are specific to bank data. It also enumerates the main action categories (search, describe, invoke, install, list_tools, subscribe/cancel, report_bug, request_mcp) making the purpose unambiguous.

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

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

The description gives explicit when-to-use guidance and alternatives: 'Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile... → invoke RUNS that tool.' It directly instructs: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT.' It also explains when invoke returns connect/checkout links and to retry after the user opens them. It also differentiates list_tools, subscribe/cancel, report_bug, request_mcp, and prompt functions, covering usage context for each major 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 mark destructiveHint=true, and the description adds that it deletes data and returns a re-connect URL. This provides useful context beyond annotations, though no mention of permissions or side effects.

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

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

Two short sentences with no wasted words. Essential information 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?

Adequate for a simple destructive tool with one parameter and no output schema, but missing parameter documentation and any mention of error conditions or what exactly is deleted.

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 'item' (string) is not explained in the description. With 0% schema description coverage, the description should clarify what 'item' refers to (e.g., bank ID or connection ID), but it remains ambiguous.

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 action (revokes consent, deletes connection data) and the resource (bank). Distinguishes from siblings like connect or list_connections by focusing on disconnection.

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

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

Describes what the tool does but provides no guidance on when to use it vs alternatives, nor any prerequisites or warnings. Implicitly clear from context but lacks explicit direction.

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?

Goes far beyond annotations by disclosing polling up to ~60s, return fields like needs_action, reconnect_url, and timed_out behavior, and clarifying it does not disconnect/reconnect.

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

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

Well-structured and front-loaded with the core action, but slightly verbose with extensive return field details; still 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?

Despite no output schema, the description covers return format thoroughly, references sibling tool for re-check, and provides enough context for correct usage.

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 fully explains both parameters: items as array of selectors (or omit for all) and wait as boolean for synchronous vs fire-and-forget.

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 re-sync of connections and waits for completion, distinguishing it from siblings like openfinance_get_item_status (for re-check) and disconnect/reconnect 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?

Explicitly says when to use ('when a balance or transaction list looks stale'), what to pass as input (items array or omit for all), and the optional wait parameter for fire-and-forget 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds critical behavioral context: BALANCE_FETCH_ERROR for CREDIT accounts, degradation to last-synced balance with realtime:false when upstream unavailable, and structured warnings. 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 adds value: endpoint, parameter constraint, error handling, response shape. Concise and well-structured, 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?

Despite no output schema, the description fully details the response shape and all error/degradation scenarios, making it complete for understanding tool behavior.

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

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

Schema has 0% coverage for the single required parameter. Description fully explains that account_ids is an array of 1-50 IDs and its purpose in fetching balances, adding essential 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 it returns real-time balance per account id via GET /accounts/:id/balance, distinguishing it from other openfinance tools by focusing on balance retrieval with specific endpoint.

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?

Specifies that account_ids must be an array of 1-50, and describes how errors are handled (warnings vs degradation). While it doesn't explicitly compare to alternatives, the usage context for balance fetching is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by warning about the provider_incident block and unreliable data during incidents, which goes beyond the 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 concise at three sentences, front-loaded with the primary purpose, then parameter details, then crucial warning. Every sentence provides essential information with 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?

Given no output schema, the description fully covers the parameter semantics, response shape (including batch structure and provider_incident edge case), and usage constraints. It is complete for a read-only batch retrieval tool with complex reliability considerations.

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: it explains the account_ids parameter is an array of 1-50 strings, describes the batch request shape (implicitly mapping to GET /accounts/:id), and details the response format {results, errors} and special provider_incident block.

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, and specifies the verb 'Returns' and resource 'account objects'. It distinguishes from siblings like openfinance_list_accounts by indicating it retrieves detailed objects per ID batch.

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

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

The description provides clear usage guidance: pass account_ids as an array (1–50), describes the batch shape {results, errors}, and warns about provider_incident block when values may be unreliable. However, it does not explicitly compare to alternatives like openfinance_list_accounts, so it loses a point for not stating when to prefer this tool.

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

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

Discloses behavioral traits beyond annotations: batch shape { results, errors }, note that Pluggy does not return paid/status field, explanation of payments[] meaning in Brazilian Open Finance. All consistent with readOnlyHint and idempotentHint.

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

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

Description is relatively long with multiple paragraphs, but every sentence adds value. Slightly verbose but justified by the complexity of the tool. Front-loaded with the main purpose and essential caveats.

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, so description explains return shape ({ results, errors }), lists fields (financeCharges, payments[], totalAmount), and warns about payments[] interpretation. Covers all necessary information for correct usage.

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 only parameter, bill_ids, is fully described: it's an array, discovery via openfinance_list_credit_card_bills, and the batch behavior. Since schema description coverage is 0%, the description carries the burden and does so thoroughly.

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 returns bill-level detail for credit card bills by id, listing specific fields. Distinguishes from siblings like openfinance_list_transactions and openfinance_list_credit_card_bills by explicitly stating what it does not do (individual transactions) and directing to alternatives.

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

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

Provides explicit guidance on when to use (get bill detail) and when not to use (not for transactions, not to reconstruct totals). Gives precise alternatives: openfinance_list_transactions for itemized transactions and openfinance_list_credit_card_bills to discover ids and check payment status. Includes caveats about payments[] interpretation and billId inconsistency.

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 it read-only, idempotent, and non-destructive. The description adds details about return fields (status, executionStatus, connector metadata, reconnect_url) and behavior differences when omitting or providing the `item` parameter.

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, but the first sentence is quite long (48 words). It conveys all necessary information efficiently without unnecessary repetition, though restructuring 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?

Given no output schema, the description provides key return elements (status, executionStatus, connector metadata, reconnect_url) and covers the two main usage modes (all banks vs. single, plus bulk). It is sufficiently complete for a straightforward status check 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 three parameters (item, item_id, item_ids) with 0% schema coverage. The description explains `item` and `item_ids`, but fails to mention `item_id`, leaving its purpose unclear. This incomplete coverage earns a 3.

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

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

The description clearly states it returns the current status of a bank connection with specific statuses, executionStatus, connector metadata, and reconnect_url. It distinguishes itself from sibling list tools by focusing on status rather than listing connections.

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

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

The description explains when to use the tool (getting status of all or a single bank connection) and how to specify a single bank (via `item`) or bulk (via `item_ids`). It does not explicitly mention 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, idempotentHint, and destructiveHint. The description adds behavioral details like batch response shape and array size limit, enhancing transparency beyond annotations.

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

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

The description is concise and front-loaded with purpose and usage, though the list of fields is somewhat long. 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 one parameter, no output schema, and existing annotations, the description provides sufficient context about the tool's purpose, input constraints, and expected output shape (batch results/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?

The single parameter loan_ids is described as an array of strings with a size limit (1-50), adding practical meaning beyond the schema's type-only definition. Schema coverage is 0%, so the description compensates well.

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

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

The description clearly states the tool returns full loan contract details by ID, enumerates specific fields, and distinguishes itself from sibling tools like openfinance_list_loans by specifying it is for deep-diving on a specific contract.

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

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

Explicitly advises use after openfinance_list_loans, describes batch shape with { results, errors }, and specifies array size limit (1-50), providing clear when-to-use and operational constraints.

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 critical behavioral context: the meaning of credit card balance (connector-dependent), provider_incident block (unreliable data), identity_notice (deduplication advice), and bulk support via item_ids. 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 very long and dense with multiple paragraphs and caveats. While every sentence adds value, it lacks structure (no bullet points or clear sections) and could be more concise for quick scanning by an AI agent.

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

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

Given the tool's complexity and no output schema, the description covers major aspects: account types, field meanings, provider incidents, identity notices, batch support, and references to related tools. It misses mention of pagination or full response structure, but is largely 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?

With schema description coverage at 0%, the description compensates by explaining the use of 'item' (single bank), 'item_ids' (batch), and 'type' (filter by BANK/CREDIT). However, it does not explicitly describe 'item_id' separate from 'item', and could be more systematic in covering each parameter.

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, distinguishing between BANK and CREDIT types with specific fields like balance, number, type, subtype, bankData, and creditData. It differentiates the account name from the brand (bank) and explains when to use each, contrasting with siblings like openfinance_list_credit_card_bills.

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 guidance: omit 'item' to list all accounts across banks, pass 'item' to target a single bank, and use openfinance_list_credit_card_bills for standardized bill amounts. It warns about connector-dependent balance meaning and provider incidents, but does not explicitly exclude cases like listing transactions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds caching behavior, response fields (id, description, etc.), and that it is a single aggregated response with no batch ids. This supplements annotations without contradiction.

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

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

Extremely concise: two sentences with no filler. The purpose is front-loaded, and every word adds value. Structure is clear and efficient.

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

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

For a parameterless, read-only list with good annotations, the description covers caching, response fields, and the relationship to another tool. No output schema is needed, and the description 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?

No parameters exist; schema coverage is 100%. The description confirms no inputs are needed, which is the baseline expected value for a parameterless tool.

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

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

The description clearly states it returns Pluggy's transaction category taxonomy via GET /categories, cached per session. It specifies the exact resource (categories) and the verb (list), and distinguishes itself from siblings by mentioning the categoryId is used by openfinance_update_transaction_category.

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 it is a read-only cache lookup, but does not explicitly state when to use it vs other list tools or when not to use it. It provides a hint by noting the categoryId usage in another tool, but lacks explicit exclusion or alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: the reconnect_url opens the widget in UPDATE mode for existing connections, does not consume a slot, and refreshes data in place. This goes well beyond what annotations provide, and there is no contradiction.

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

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

The description is concise (3-4 sentences), front-loaded with purpose, and each sentence adds unique value. There is no fluff. The structure clearly separates the main return description from the special behavior of reconnect_url.

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

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

For a read-only list tool with no parameters and no output schema, the description is mostly complete. It explains the return values and the purpose of reconnect_url. Minor gaps: it does not mention if the list includes all connections regardless of status, or how the add_connection_url is used exactly. But overall it covers the essential context.

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

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

With 0 parameters and 100% schema description coverage, the description adds value by detailing the returned fields and explaining the two URLs (reconnect_url and add_connection_url). Baseline for 0 params is 4, and the description fully compensates for lack of parameters.

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

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

The description uses a specific verb 'Returns' and resource 'saved bank connections', and lists the exact fields returned (connector_id, item_id, bank name, etc.). It clearly distinguishes from sibling tools like openfinance_disconnect_bank by explaining the reconnect_url behavior, making the tool's unique role very clear.

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

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

The description gives explicit guidance on when to use the reconnect_url (for re-authentication, MFA connectors, LOGIN_ERROR, stale data) and notes it does not consume a connection slot or require disconnecting. However, it does not explicitly address when to prefer other sibling tools like openfinance_force_sync or openfinance_get_item_status, which could be clarified.

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, meaning no side effects. The description adds significant behavioral context beyond annotations: it explains the payment cycle semantics, the derived payment_status logic, connector asymmetry (open bill not retrievable), and potential unreliability of billId grouping. 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 very long and dense, covering many details in a single block. While it front-loads the main purpose, it lacks clear structure (e.g., sections, bullet points) and contains some redundancy (e.g., repeated warnings about payment_status). It would benefit from being more concise and organized.

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 (5 parameters, no output schema, 0% schema coverage), the description is remarkably complete. It explains return values, edge cases (connector asymmetry, payment timing), derived fields (payment_status, open_bill), parameter behavior, and cross-references to other tools. 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?

Schema description coverage is 0%, so the description carries full burden. It elaborates on all five parameters: account_id (required), account_ids (bulk support), page/page_size (pagination), include_open_bill (opt-in for open bill and total debt). It explains the meaning and usage of each, far exceeding what the schema provides.

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 'CLOSED credit card bills for a CREDIT-type account' and lists the specific fields (dueDate, totalAmount, etc.). It distinguishes from sibling tools by mentioning that for itemized transactions, one should use openfinance_list_transactions, and for a single bill, openfinance_get_credit_card_bill exists.

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 usage guidelines: it explains when to use include_open_bill (opt-in), how to interpret payment_status (e.g., 'PAID' vs 'PAST_DUE_UNCONFIRMED'), and when NOT to use the tool for certain inferences (e.g., 'do NOT assume this bill was paid just because payments[] is non-empty'). It also warns about connector asymmetry and recommends using openfinance_list_transactions for individual transactions.

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 that mark the tool as read-only and idempotent, the description adds important behavioral details: error handling (returns instead of throwing on 403), data integrity warnings for suspicious zero balances, and bulk execution support. This greatly aids agent decision-making.

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

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

The description is relatively long but well-structured: purpose first, then details on response, error handling, data integrity, and bulk support. Each sentence adds value, though some could be tightened without losing 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 adequately covers the return format (fields like balance, amount, rates, due date) and special behaviors (data integrity warnings). Pagination and item parameter are mentioned but not elaborated, keeping completeness slightly below full.

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 partially compensates by explaining the 'item_ids' parameter for bulk and implicitly documenting 'type' via listed asset types. However, 'item', 'page', 'page_size', and 'item_id' are not explained.

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

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

The description clearly states the tool returns the investment portfolio for a connection and lists asset types. However, it does not explicitly differentiate from sibling tools like openfinance_list_investment_transactions, though the distinction is implicit from the naming.

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 versus alternatives (e.g., openfinance_list_accounts, openfinance_list_investment_transactions). The description only covers functionality, not usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by detailing the types of transactions and fields returned, including expenses breakdown. 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 two paragraphs, clear and informative. Could be more structured (e.g., bullet list of fields), but remains concise and front-loaded.

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

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

No output schema, but description lists many fields (quantity, value, netAmount, expenses). Covers key behavioral and semantic aspects. Parameter documentation could be improved for page/page_size.

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 with 0% description coverage. Description mentions investment_id implicitly and bulk support for investment_ids, but does not explain page, page_size, or the format of investment_ids array. Minimal added meaning beyond schema.

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

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

Description clearly states it returns movement history for investment positions, listing specific transaction types (BUY, SELL, etc.) and fields (quantity, value, netAmount, etc.). Distinguishes from sibling tools like openfinance_list_investments 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?

Explicitly says to use after openfinance_list_investments to get investment_id. Mentions bulk support with investment_ids. Does not explicitly exclude when not to use, but provides clear context for 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?

Annotations provide readOnlyHint, idempotentHint, destructiveHint, so safety is clear. Description adds behavioral details: sequential queries with rate-limiting, return format `{ results, 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?

Two sentences, each essential. First states purpose and endpoint. Second explains parameter usage and behavior. No redundant or missing parts.

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 purpose, parameter usage, return format, and behavioral compliance (rate limits). Without output schema, return format is mentioned. Could add pagination or limits, but current level is adequate.

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

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

Schema coverage is 0%, so description fully compensates: explains `items` as connection selectors (item_id uuid, connector_id, connector_name), one per connection, and the effect of omitting the parameter.

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?

Describes listing loan contracts per bank connection via GET /loans. Clearly distinguishes from siblings like openfinance_get_loan_detail (detail) and openfinance_list_accounts (accounts vs loans).

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

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

Explains when to pass `items` (specific connections) versus omit (all banks), and notes sequential fetching with rate-limit spacing. No explicit when-not-to-use, but context from siblings fills gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds critical behavioral context: pagination modes (auto vs manual), error response format (returns structured warning instead of throwing), detail level behaviors (compact/rich/raw), credit card metadata limitations (per-connector hints, sparse population), and provider incident handling.

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 into logical sections (purpose, credit card specifics, date filters, pagination, detail levels, error handling, bulk support) but somewhat verbose. Could be condensed without losing key warnings and edge cases.

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 8 parameters and no output schema, description covers all needed context: response structure (account echo, total, results, warning, error), truncation handling, provider incident block, and cross-check guidance for multiple banks. Also addresses zero-total credit accounts with diagnostic steps.

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, but description fully compensates by explaining each parameter: from/to as ISO YYYY-MM-DD, pagination controls (page, page_size with defaults and max), detail enum (compact/rich/raw with token cost and coverage), search_queries (case-insensitive, OR semantics, 5000 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?

Clearly states verb 'Returns transactions' and resource 'bank account (BANK or CREDIT type)'. Differentiates from siblings like openfinance_list_credit_card_bills and openfinance_get_credit_card_bill by specifying this is the ONLY way for credit card 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?

Provides extensive guidance: when to use (credit card itemized transactions), when not to (reconstructing bill totals), and alternatives (openfinance_list_credit_card_bills for standardized totals, openfinance_get_item_status for connection health). Also warns about connector-specific behavior and provider incidents.

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

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

The description adds significant behavioral context beyond annotations: it discloses that transactions are capped at 5,000 per account with a truncated:true flag, mentions provider_incident block for open incidents affecting data completeness, and explains the different output structures for granularity and detail options. This fully covers the tool's 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?

Despite length, every sentence adds value and is well-structured: it front-loads the core purpose, then details parameters, output modes, limits, and edge cases. The structure is logical and efficient, 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?

For a tool with 9 parameters, no required params, no output schema, and no schema descriptions, the description is remarkably complete. It covers default behavior, output details (por_mes, top_despesas, etc.), truncation limits, and provider incidents. No major 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?

With 0% schema coverage, the description fully compensates by explaining all parameters and their values: item accepts connector_id/connector_name/item_id, from/to are ISO dates, granularity defaults to 'monthly' and affects output shape, type filters BANK/CREDIT, detail levels (compact/rich/raw) with behavior, top_n, and item_ids for bulk. It also describes the output structure implicitly.

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

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

The description clearly states the tool provides consolidated cash-flow analysis for a whole bank connection in one call, resolving accounts internally. It distinguishes from siblings by noting it avoids the need to call openfinance_list_accounts first, and specifies the use cases for analyzing monthly/annual cash flow, income/expenses, and top spending/receipts.

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 usage guidance, including when to use each granularity and detail level, and notes the tool is for connection-level analysis. It contrasts with needing to call openfinance_list_accounts first, but does not explicitly compare to sibling tools like openfinance_list_transactions, though the context implies differentiation.

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

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

Beyond annotations (readOnly, idempotent, not destructive), the description adds transparency by detailing the source (public status page), return fields (global indicator, degraded components, incidents, affected banks), and the 'your_banks_affected' feature. No contradictions with annotations.

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

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

Single coherent paragraph, front-loads purpose and use case. Efficiently covers when, why, and what is returned. Slightly wordy but 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 thoroughly explains return values and use case. It fully prepares the agent to interpret results and decide when to use the tool.

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

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

No parameters in schema (0 params baseline 4). Description does not need to explain parameters as there are none.

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

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

The description clearly states the tool checks the LIVE operational status of the Open Finance provider, distinct from connection status. It specifies the exact purpose: monitoring provider health and identifying upstream outages.

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 (data incomplete/stale despite updated connection) and when not (differentiates from openfinance_get_item_status). Provides clear guidance for distinguishing 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that some connectors have a 'caveat' warning about needing periodic reconnection, which is critical behavioral transparency. Also explains the plan-dependent visibility and the hint behavior for missing keywords. 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 a single dense paragraph that packs many details. It is well front-loaded with the core purpose, and every sentence adds value. However, it could be slightly more structured (e.g., bullet points) to improve scanability. Still highly 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 adequately explains the return values (connector id, access, audience, linked connections/accounts, connect_url, caveat). It also covers edge cases (missing keywords, plan differences). For a tool with many siblings, this description provides complete context for correct invocation.

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

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

Schema has 0% description coverage, but the description fully explains both parameters: keywords as an array of strings (with example ['nubank','btg']) and that include_accounts triggers accounts inclusion. This adds substantial meaning beyond the bare schema.

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

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

The description clearly states it searches bank connectors by name (keywords array) and returns specific fields (id, access, audience, links, connect_url). It also mentions caveat warnings and plan handling. This is a specific verb+resource with clear scope, distinguishing it from siblings like 'connect' or 'authenticate'.

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 'Call this BEFORE connecting to hand the user a one-click link' and notes that keywords are required (returns hint otherwise). Also explains plan behavior (PF/PJ segregation). Provides clear when-to-use and what-not-to-do, differentiating from alternatives.

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

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

Annotations provide basic hints, but the description adds critical behavioral details: it overrides automatic categorization, teaches Pluggy by creating a Category Rule, and explains batch error handling. This goes well beyond what annotations provide.

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

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

The description is well-structured: it starts with the core action, then explains the parameter format, then the behavioral impact, then the return format. Every sentence adds value without redundancy.

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

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

Given no output schema, the description provides a complete picture of inputs, side effects, and response structure. It addresses all key aspects a user would need 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?

Schema description coverage is 0%, but the description fully compensates by explaining the `items` array structure, the required fields transaction_id and category_id, their sources, and the exact response shape including per-item errors.

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 corrects transaction categories, specifies the HTTP method PATCH /transactions/:id, and distinguishes from sibling tools by referencing openfinance_list_transactions and openfinance_list_categories for obtaining the required 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 explains when to use the tool (to fix miscategorized transactions) and describes the side effect of creating a Category Rule. It does not explicitly state when not to use it, but the context is clear and alternatives are implied via sibling references.

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 non-read-only, non-destructive, idempotent. Description adds reproduction instructions. No contradictions. Could mention that reports are sent to developers.

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

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

Two concise sentences, first defines purpose, second gives key usage tip. 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 simple bug report tool, provides essential info but lacks outcome details (e.g., creates ticket, sends to team). Acceptable but could be more 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?

With 0% schema coverage, description partially explains conversation parameter but leaves context and message undocumented. Message is required but no details on expected format.

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

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

Description clearly states verb (report) and resource (bug, missing feature, feedback). It distinguishes from sibling tools, which are mostly unrelated to bug reporting.

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

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

Explicitly tells when to use (for bugs/feedback) and provides guidance to include conversation array. Lacks explicit when-not-to-use, but siblings are distinct so not critical.

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 context of what versions are shown, which is consistent and sufficient.

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 with no wasted words. Perfectly concise for a simple version 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?

For a zero-parameter, read-only tool with complete annotations, the description fully covers what an agent needs to know. No output schema required for simple string result.

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; baseline 4 applies. No additional semantics 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?

Description clearly states the tool shows current MCP platform and adapter versions. Specific verb 'show' and resource 'MCP platform and adapter versions' makes 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?

No sibling tools perform similar function, so no alternatives needed. Description implies usage for checking versions, but no explicit when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about what information is returned, going beyond annotations without contradicting them.

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

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

The description is a single, well-structured sentence that immediately states the outcome and lists the key data points. Every clause adds value with no redundancy.

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

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

Although there is no output schema, the description enumerates the categories of returned information, which is sufficient for a read-only informational tool. No additional context is needed given the sibling list and annotations.

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

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

The tool has zero parameters, so there is no schema to elaborate. Baseline 4 is appropriate since the description needs no parameter detail.

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 ('Returns') and identifies the exact resource ('current toolkit state'), listing concrete components (installed MCPs, connection status, accounts, catalog tool counts). This clearly distinguishes it from siblings like connect or authenticate.

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 inspect the toolkit's current state, such as installed MCPs and connection status) and indirectly contrasts with action-oriented siblings like connect or authenticate. It does not explicitly state exclusions or alternatives, 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.