Á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 only declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial context beyond this: the balance is a snapshot anchored to the last upstream sync rather than a live read, updateDateTime/updatedAt reflects the sync instant, credit accounts can surface BALANCE_FETCH_ERROR/BALANCE_CONSENT_ERROR as structured warnings instead of throwing, consent recovery requires reconnecting the bank, and upstream 5xx or non-Open-Finance connectors degrade to warnings. None of this contradicts the annotations; it richly supplements 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 dense and long, but every sentence earns its place — snapshot semantics, force_sync routing, batch limit, and two distinct error modes are all substantive. It is front-loaded with the core function before caveats. It earns a 4 rather than 5 because the error-handling material is packed into a long middle paragraph without structural separation, making it heavier to parse than necessary.

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

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

With no output schema, the description must convey what the agent will receive, and it sketches the row structure (updateDateTime/updatedAt, structured warnings) while fully covering the behavioral gotchas: freshness limits, batch cap, error codes, and the recovery workflow. The one gap is that the full success response shape (e.g., balance amount fields) is only implied by the tool name, not stated.

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

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

Schema coverage is 0%, so the description must compensate, and it does: 'Pass `account_ids` as an array (1–50)' adds a batch-size bound and per-account-id semantics that the bare schema (array of strings) does not provide. It does not describe id format or invalid-id behavior, but for a single required parameter this is meaningful compensation.

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 first sentence names a specific verb and resource — 'Returns the latest available balance per account id' — and pins it to an explicit endpoint (GET /accounts/:id/balance). The snapshot qualifyer ('freshest balance the provider can serve') sharpens what the tool actually returns. It also distinguishes itself from the relevant siblings by referencing openfinance_list_transactions and openfinance_force_sync inline, so an agent can tell it apart from list/account-detail tools.

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

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

The description gives explicit routing: if a just-happened movement is missing or the balance disagrees with the sum of openfinance_list_transactions, use openfinance_force_sync and then re-read. This names the alternative tool, the exact condition that selects it, and the follow-up step, leaving nothing to inference.

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?

Annotations only state read-only/idempotent; the description adds the dangerous domain beware: an extra full account transaction cost when opting in ('costs a full extra transaction translation scan of the true'), `transactions_basis` semantics with `confidence:'low'` estimates, the hard warning that `totalAmount` is authoritative and must not be rebuilt from transactions, and the counter-intuitive Plncy Open Finance reality — `payments[]` typically reflects the PREVIOUS bill's payment, so non-empty does not mean this bill was paid. No contradiction with the readOnly 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 — a single dense paragraph — but front-loads the core purpose and every subsequent sentence carries non-redundant value (cost, basis, paid-status caveat, batch shape, field semantics). It loses a point for being much heavier than needed to name the kernel; a few one-off phases could be structured heads (e.g., a short section for 'paid status caveat. Still, its content density is justified by the domain'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?

For a read tool with a complex domain (open finance, bill-transaction coupling), the description covers, beyond the schema, the answer fields, the opt-in flows with their conditions, the reliability tiers, the batch shape `{ results, errors }`, the discovery sequency via siblings, and the paid-status workaround. The tool answers what an agent would need to avoid both improper cost (extra scan) and semantic misinterpretation (payments vs prevalence). The only missing piece is the `transactions_detail` enum meaning, covered above, but given the enormous amount of context already present, that is a minor omission.

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

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

The schema has 0% description coverage, so the description must compensate — and it strongly does for three key parameters: `bill_ids` (must be an array; discover via sibling), `account_id` (needed only when include_transactions:true, because the bill disнять the account refinement), and `include_transactions` (what it adds, its cost, and its basis). However, `transactions_detail` (enum: compact/rich/raw) is never mentioned in the description; an agent cannot tell what that parameter authorizes, which is a significant missing piece.

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 opens with a specific verb and resource: 'Returns bill-level detail for one or more credit cards bills by id', immediately contrasting with siblings `openfinance_list_credit_card_bills` (discover ids / paid status) and `openfinance_list_transactions` (fetch itemized purchases). With the named endpoint and field objects, an agent knows exactly what this tool is and how it's different from a search-by-list sibling.

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 when-to/ when-not-to: 'use openfinance_list_credit_card_bills first to discover ids'; 'To check paid status, prefer openfinance_list_credit_card_bills which derives payment_status via cross-bill match'; and uses conditions like 'Pass include_transactions:true... if you also fetch transactions by yourself via openfinance_list_transation'. It even tells when transactions are only an estimate (OPEN bills) vs exact (CLOSED bills), leaving nothing to inference.

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?

The description goes well beyond the readOnlyHint/idempotentHint annotations by disclosing connector-dependent credit balance semantics, stale provider-reported fields, provider_incident reliability concerns, and identity_notice deduplication rules. This is a rich behavioral disclosure that materially prevents incorrect agent actions, such as telling a user a card has no balance when balance_notice is present.

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

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

The description is dense with operational caveats, but each sentence contributes a distinct behavioral fact needed for correct use. It is front-loaded with the tool's basic return shape and then layers edge-case warnings. It is longer than a typical description, yet earned by the complexity of Open Finance data semantics and the importance of preventing misinterpretation.

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

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

Given no output schema and 0% parameter coverage in the schema, the description is unusually complete. It covers return shape, field semantics, filtering behavior, bulk support, reliability caveats, and cross-tool routing to openfinance_list_credit_card_bills for standardized amounts. An agent has enough context to select and use the tool correctly in almost all 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 coverage is 0%, so the description must carry the parameter semantics. It explains the meaning and effect of `item` clearly, and mentions `item_ids` for bulk support. It does not explicitly document the `type` filter in prose, but the schema enum already covers that; the description still does substantial work for the most nuanced 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 starts by stating exactly what the tool returns: accounts for a bank connection with BANK and CREDIT types, listing key fields. It further distinguishes the tool from siblings by mentioning openfinance_list_credit_card_bills and openfinance_force_sync as complementary alternatives, which makes its purpose and boundaries 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 provides explicit when-to-use guidance: pass `item` to target a single bank and omit `item` to list accounts across all linked banks. It also clearly warns against misusing `balance` for credit cards and directs agents to openfinance_list_credit_card_bills for standardized bill data, covering exclusions and alternatives.

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

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

Annotations already declare readOnlyHint, 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?

The description adds substantial behavioral detail beyond the readOnly/idempotent/destructive hints: auto-pagination up to a 5000 ceiling, `truncated:true`, manual pagination semantics, non-throwing error response shape, `provider_incident` blocks, scheduled/future rows, per-connector credit-card PENDING vs POSTED variation, and the `account` echo block. No statement contradicts 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 long but well organized with topic blocks (CREDIT, SCHEDULED, PAGINATION, `detail`), and it front-loads the core purpose. There is some redundancy: the billId caveat is explained both in the general paragraph and again under `detail:'rich'`. It earns its place for the most part, but a 5 would require trimming that repetition while preserving the necessary 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?

The description is nearly complete for a tool with no output schema: it covers return shape, error behavior, pagination, edge conditions, provider incidents, and cross-reference to sibling tools. The only meaningful completeness gap is the undocumented `account_ids` batch parameter, which appears in the input schema but is not explained; otherwise an agent would know how to invoke and interpret this tool correctly.

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

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

With schema description coverage at 0%, the description carries the entire parameter burden and does so well: `from`/`to` date format, `search_queries` behavior, `page`/`page_size` semantics, and `detail` modes/effects are all clearly explained. However, `account_ids` never appears in the description, and `account_id` is only implied through the phrase 'share one account_id' and the response echo block rather than being explicitly tied to 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?

Description opens with a specific verb+resource: 'Returns transactions for a bank account (BANK or CREDIT type).' It also distinguishes itself from related sibling tools by stating that for CREDIT accounts it is the ONLY way to get itemized transactions, and it points to openfinance_list_credit_card_bills for bill-level totals. This goes well beyond the tool name and gives an unambiguous 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 provides explicit when-to-use guidance and exclusions: 'To get a standardized open-bill total / total debt regardless, use openfinance_list_credit_card_bills', 'For closing/due dates use openfinance_list_accounts', and 'To list only what actually happened, pass `to` = today.' It also gives alternative error-handling steps via openfinance_get_item_status / openfinance_force_sync. The agent can decide when this tool is appropriate versus a sibling.

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.