Necton MCP

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds context about the two login modes and the non-expiring nature of config-based auth. It does not contradict annotations and provides behavioral details beyond them, such as the idempotent nature of calling with or without token.

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

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

The description is informative but slightly verbose. It front-loads the purpose and then explains both use cases efficiently. Every sentence adds value, though it could be trimmed slightly without loss.

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 one optional parameter, the description fully covers the authentication workflow, including permanent vs session options and step-by-step guidance. It is complete enough for an agent to invoke correctly.

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

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

With 0% schema description coverage, the description compensates fully by explaining that the optional 'token' parameter is a JWT for session login, and that omitting it returns a login link. This adds crucial semantic meaning missing from the schema.

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

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

The description clearly states that the tool is for authentication, explaining two modes: browser login with token paste or config-based permanent login. This distinguishes it from sibling tools like 'connect' and provides specific verb-resource mapping.

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 it: for logging in, with options to either paste a token for session-only login or add it to config for permanent access. It also implies the alternative of config-based login for permanent connections, which helps the agent choose correctly.

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 the tool as read-only, idempotent, and non-destructive. The description adds value by detailing the return format for two scenarios (all connected vs missing credentials), going beyond the annotations.

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

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

The description is two sentences, about 40 words, front-loaded with the main purpose. Every phrase is informative with no redundancy.

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

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

Given no output schema and simple behavior, the description covers the two main states of the connection. It could mention error handling or other edge cases for completeness, but it suffices for a straightforward status check.

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, and schema coverage is trivially 100%. Per guidelines, a baseline of 4 is appropriate since no parameter info is needed, and the description adds context about output behavior.

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

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

The description clearly states the tool returns connection status and URLs, using a specific verb-resource combination. It distinguishes itself from siblings like 'authenticate' by focusing on connection status rather than authentication flow.

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

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

The description provides clear context on when to use the tool (to check connection status) and what to expect in different states (all connected vs missing credentials). It does not explicitly state when not to use it, but the contrast with siblings like 'authenticate' is evident.

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 exceeds the annotations' minimal safety hints by revealing critical behaviors: invoke works even when the MCP is not installed, returns a connect link if credentials are needed, and returns a checkout/top-up link for paid tools with an empty wallet. It also discloses that writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin, and that search/describe flag installation status.

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 covering a large, multi-action tool. It is front-loaded with the core purpose and flow, then expands into prompts and permissions. Every sentence adds value, but the lack of bullet points or section breaks makes it harder to scan. It is appropriately sizable for a 14-action tool, though borderline verbose.

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

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

For a tool with 14 actions, 23 parameters, and no output schema, the description provides a remarkably complete operational picture. It covers discovery, execution, installation, billing, permissions, auth, one-off behavior, and the prompt library. An agent can correctly select actions and understand the primary workflows, edge cases (credential/checkout), and authorization constraints without external documentation.

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

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

With 0% schema description coverage, the description carries the burden of explaining parameters. It clarifies the action enum values (search, describe, install, invoke, list_tools, subscribe/cancel, report_bug, request_mcp, and prompt-related actions), and mentions tool_id, but leaves several parameters (e.g., immediate, tier_slug, cancel_reason, prompt_vars, conversation) unexplained. The description meaningfully compensates for the schema gap but not fully.

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 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' which clearly defines the tool's dual role. It explicitly differentiates from sibling tools (e.g., openfinance_* and authenticate) by positioning itself as the central hub for finding, describing, invoking, and installing MCPs, plus prompt management.

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: 'Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile... so you pick the right tool_id → invoke RUNS that tool.' It further states 'Use install only to make an MCP PERMANENT' and 'prefer invoke for a single/occasional use,' directly advising on alternative actions. It also covers when to use list_tools, subscribe/cancel, and the prompt-library functions.

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 set destructiveHint=true; the description adds clarity by stating data will no longer be available and mentions the return of an add_connection_url, providing extra behavioral context.

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

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

Two clear, front-loaded sentences with no extraneous information; every sentence adds value.

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

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

Missing parameter explanation and lack of error handling or prerequisites for this destructive action; return value is mentioned but output schema is absent, leaving gaps in completeness.

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

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

The sole parameter 'item' is not explained in the description or schema (0% coverage). The description mentions 'a specific bank' but fails to clarify that 'item' likely refers to an identifier.

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

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

The description clearly states the tool revokes consent and deletes connection data for a specific bank, distinguishing it from sibling tools like openfinance_list_connections or connect.

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

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

The description implies use when you need to disconnect a bank, but lacks explicit guidance on when not to use or alternatives like listing connections first.

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

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

The description discloses non-obvious behaviors: it polls up to 60s, returns detailed results including status, executionStatus, and potential needs_action with reconnect_url. Annotations only provide basic hints, so the description carries the burden well without 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 verbose but every sentence adds value, covering purpose, usage, parameters, returns, and edge cases. It is front-loaded with the main action. Minor reduction possible, but structure is clear.

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 detailed return format and error explanations (needs_action, timed_out, reconnect_url). The complexity of syncing and waiting is fully addressed, making the agent capable of using 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?

The description fully explains both parameters: items as an array of selectors (item_id, connector_id, connector_name, custom_label) and the optional wait boolean. Since schema coverage is 0%, the description compensates completely, adding meaning beyond the schema.

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

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

The description clearly states the tool forces a bank to re-sync connections and waits for completion. It specifies the HTTP method (PATCH) and polling behavior, differentiating it from sibling tools like openfinance_get_item_status.

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

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

The description explicitly advises using this tool when balances or transactions look stale, and provides guidance on fire-and-forget mode with wait=false. It also instructs to re-check with openfinance_get_item_status on timeout, offering clear when-to-use and when-not-to-use 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description richly explains behavioral nuances: the balance is a snapshot tied to the last upstream sync, updateDateTime is not a live instant, credit accounts can return structured warnings instead of throwing, and upstream 5xx or non-Open Finance connectors cause rows to degrade. This significantly exceeds what the annotations alone convey.

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

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

The description is front-loaded with the core action and then layers in caveats in a logical order. It is longer than the minimal case but every sentence adds necessary operational detail; the only structural flaw is the final sentence ending with an incomplete 'DEGRADES to ...'.

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 there is no output schema, the description does a strong job covering freshness semantics, error modes, and recovery via force_sync. However, it never explains how to obtain the account_ids and leaves the degradation behavior incomplete, which slightly weakens an otherwise thorough definition.

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

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

The input schema only defines account_ids as an array of strings, so the description's instruction to pass it as an array of 1–50 items adds valuable bounds. It could further explain where account_ids come from or what format they take, but the single parameter is self-explanatory enough for competent use.

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 the latest available balance per account id' and even gives the endpoint GET /accounts/:id/balance. It clearly differentiates this tool from siblings by framing it as a snapshot/read operation, not a list or sync tool.

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

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

The description gives explicit usage context: use this for the freshest served balance, but if data may be stale or disagrees with openfinance_list_transactions, run openfinance_force_sync and re-read. It also explains when errors like BALANCE_CONSENT_ERROR occur and how to resolve them, giving practical routing 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?

Beyond idempotent/read-only annotations, describes provider_incident block causing unreliable data and warns not to present those values as real. Also mentions batch err 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?

Three sentences: purpose, parameter+batch, incident warning. No wordiness, front-loaded with core function.

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 parameter constraint, batch shape, incident warning. No output schema, so missing detailed return fields list is acceptable given the purpose description.

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

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

With 0% schema coverage, description adds array size constraint (1-50) and batch shape. Provides more than schema's bare type definition.

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

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

Description clearly states verb 'Returns', resource 'full account objects including extended creditData per id'. It distinguishes from openfinance_list_accounts by specifying per-id detail and mentions the batch shape.

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

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

Explicitly instructs to pass account_ids as array (1-50) and describes batch response shape. Lacks explicit when-not-to-use 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.

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavior beyond that: the bill payload lacks transactions (they live on the account), the transactions_basis can be exact vs estimate with confidence:'low', the totalAmount is authoritative and must not be reconstructed by summing transactions, and the payments[] semantic warning. The description does not contradict any annotation.

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?

Dense but earned: every sentence of this long description carries value — batch shape, field semantics, bill-closing boundaries, basis semantics, paid-status caveat, opt-in cost. Front-loaded with the main purpose, organized via explicit markers (OPT-IN, NOTE). The lack of subheadings and heavy inline parentheses make it less scannable than it could be, but this is a small cost for the complexity of the domain.

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

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

For a tool with no output schema, 4 parameters, and high domain complexity, the description is very complete: return fields, batch result shape, transaction matching semantics, cost trade-off, and routing to sibling tools are all covered. The remaining gap is the undocumented transactions_detail parameter, which is significant enough to drop this from a perfect score.

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

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

Schema description coverage is 0%, so the description must compensate. It does for three of the four parameters: bill_ids (array usage and discovery path), include_transactions (cost, required account_id, resulting fields), and account_id (why it is needed). Missing entirely is the transactions_detail parameter (compact/rich/raw enum) — it is never mentioned in the description.

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 precise verb-resource-scope statement: 'Returns bill-level detail for one or more credit card bills by id', including the exact HTTP mapping GET /bills/:id. It distinguishes itself from sibling tools by naming the such boundaries: list bills vs get bill detail vs 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?

Explicit when-to-use and workflow guidance: use openfinance_list_credit_card_bills first to discover bill_ids, use openfinance_get_credit_card_bill for detail, and use openfinance_list_transactions with the account_id and a from/to range ending at billClosingDate to fetch transactions manually. It also explicitly says to check payment_status via openfinance_list_credit_card_bills rather than assuming payments[] means the bill was paid.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing safety and idempotency. The description goes beyond by detailing the reconnect_url behavior (reauthentication without disconnecting), the response structure for bulk (count, items), and the executionStatus field. There is no contradiction with annotations, and the description adds significant behavioral context.

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

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

The description is moderately concise, providing essential information in a structured manner. It front-loads the primary purpose and then elaborates on usage patterns. While every sentence adds value, the description could be slightly more terse, especially by combining the lines about bulk support. Overall, it is well-organized and readable.

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 lack of an output schema, the description adequately covers the return fields (status, executionStatus, connector metadata, reconnect_url) and differentiates between single and bulk responses. It addresses the main usage scenarios. However, it does not mention error conditions or edge cases (e.g., what if an invalid item is given). For a read-only status tool, this is acceptable but not exhaustive.

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

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

Although the input schema has 0% coverage (no parameter descriptions), the description explains how to use 'item' and 'item_ids' effectively: omitting item returns all, passing item returns single, and item_ids enables bulk. However, it does not clarify the difference between 'item' and 'item_id' (both in schema), leaving some ambiguity. This prevents a perfect score because the description should explain all parameters.

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

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

The description clearly states the tool returns the current status of a bank connection, listing specific fields (status, executionStatus, connector metadata, reconnect_url). It distinguishes between retrieving all connections versus a single one, and mentions bulk support with item_ids. Compared to sibling tools like openfinance_list_connections, which likely lists connections without status details, this tool's purpose is specific and well-defined.

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

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

The description provides clear context on when to use the tool: to get connection status. It explains different usage patterns (omit item for all, pass item for single, use item_ids for bulk). However, it does not explicitly state when not to use it or contrast with similar sibling tools like openfinance_list_connections or openfinance_provider_status. This omission prevents a higher score.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds batch behavior (`{ results, errors }` shape) and limit (1-50). No contradiction; adds useful context beyond annotations.

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

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

Description is a single long sentence with inline list; packs information but could be more structured (e.g., bullet points). Somewhat verbose but functional.

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

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

No output schema exists, but description enumerates major fields (interestRates, charges, amortization, etc.) and mentions batch shape. Sufficiently complete for the tool's single parameter and read-only nature.

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 explains parameter `loan_ids` is an array of strings with size 1-50 and notes batch response shape. This compensates for missing schema description.

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 detail by ID and lists specific fields. It distinguishes from sibling openfinance_list_loans by explicitly stating 'Use after openfinance_list_loans to deep-dive 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?

Provides explicit usage guidance: 'Use after openfinance_list_loans to deep-dive on a specific contract.' Also mentions parameter range (1-50) and response shape. Does not state when not to use, but context is sufficient.

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

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

Annotations only provide readOnly/idempotent/destructive hints. The description adds substantial behavioral context: connector-dependent `balance` meaning, `balance_notice` indicating a misleading zero, lagging `bankData` fields, `provider_incident` indicating unreliable values, and `identity_notice` requiring dedupe by account number. All of this goes well beyond the annotations and materially changes how an agent should interpret and present the response. No contradiction with annotations exists.

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

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

The description is long, but the length is earned by the density of real operational caveats. The main return value and key usage rule are front-loaded in the first sentence. Some organization into paragraphs or bullets would improve scannability, but no sentence appears redundant.

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

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

For a tool with no output schema and several subtle behavioral hazards, the description covers return fields, bank scoping, batch mode, credit-card balance pitfalls, provider incidents, data lag, and deduplication rules. An agent has enough context to call the tool correctly and interpret even edge-case responses without external assumptions.

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 carries the full burden for parameter meaning. It explains `item` (target a single bank), omitting `item` (list across all banks), and `item_ids` (batch). The `type` parameter is implied through BANK/CREDIT categories, though not explicitly tied to the parameter. `item_id` singular is not clearly differentiated from `item`, which prevents a perfect score.

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 precise verb and resource: 'Returns accounts for a bank connection: BANK ... and CREDIT ...' and enumerates the exact fields returned. It also distinguishes itself from openfinance_list_credit_card_bills at the point where a reader might confuse account balance semantics with bill amounts. This is a clear, specific purpose statement.

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 omit `item` versus pass it, when to use batch `item_ids`, and when to route to openfinance_list_credit_card_bills instead. It directly addresses the common user-facing query 'my accounts/cards' and specifies that the alternative tool should be used for standardized bill amounts. This is actionable routing guidance, not just a hint.

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

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

The description adds behavioral context beyond annotations: it mentions caching per session, single aggregated response with no batch ids, and the structure of each entry (id, description, descriptionTranslated, parentId, parentDescription). Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and the description complements them effectively.

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

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

The description is concise: three sentences that front-load the main purpose, then detail the response fields, and finally note caching/batch behavior. 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 the tool's low complexity (no parameters, read-only, idempotent), the description fully covers what an agent needs: what it returns, caching, use of ids by sibling, and output structure. No gaps are evident.

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

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

There are no parameters (0 params), so the baseline is 4. The description provides value by detailing the output fields (id, description, descriptionTranslated, parentId, parentDescription) which are not covered by an output schema. This extra semantic information helps the agent understand what the tool returns.

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 transaction category taxonomy, identifies the underlying API endpoint (GET /categories), and distinguishes from sibling list tools by specifying the resource type. It also mentions the caching behavior and the use of `id` by a related tool.

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

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

The description provides implicit usage guidance by noting that `id` is used by `openfinance_update_transaction_category`, suggesting this tool should be called before that one. It also advises preferring `descriptionTranslated` for pt-BR users. However, it does not explicitly state when not to use this tool or compare with 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 indicate safe read operation (readOnlyHint, idempotent, non-destructive). Description adds behavioral details about reconnect_url and add_connection_url, enhancing transparency beyond structured fields.

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 core purpose, each sentence adds value. 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, description completely explains return values and their purposes. Agent can correctly invoke and interpret results.

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 to document (schema empty), baseline is 4. Description fully covers return value semantics, meeting the need.

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 saved bank connections with specific fields (connector_id, item_id, bank name, etc.) and distinguishes from sibling list tools like openfinance_list_accounts.

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

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

Explicitly describes when to use the reconnect_url (re-authentication, MFA, LOGIN_ERROR, stale data) and what it does not do (no slot consumption, no disconnect required). Slightly lacks explicit 'when not to use' but provides strong 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 indicate readOnlyHint and idempotentHint, which align with the non-destructive nature. The description adds extensive behavioral context: payment status derivation logic, cross-bill payment matching, open bill generation conditions, connector asymmetry, and reliability 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?

The description is very long and includes many detailed sections. While each section adds necessary value for the complex Brazilian Open Finance semantics, the overall length could be trimmed without losing critical information. It front-loads the main purpose but becomes dense quickly.

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

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

Given the complexity (5 parameters, multiple derived fields, no output schema), the description covers all necessary aspects: return fields, derived payment_status, open bill conditions, connector asymmetry, warnings, and cross-references to other tools. It ensures an agent can correctly invoke and interpret results.

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 bears the burden. It explains include_open_bill and account_ids in detail, and mentions pagination parameters implicitly but does not format or limit info. The required account_id is defined only as 'account_id' without further clarification. Some parameters lack added semantics, but the critical ones are well-covered.

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

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

The description clearly states it returns CLOSED credit card bills for a CREDIT-type account, with a list of specific fields. It distinguishes itself from siblings like openfinance_list_transactions and openfinance_get_credit_card_bill by noting appropriate use cases.

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

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

The description provides explicit guidance on when to use this tool (for bill-level summaries) versus when to use openfinance_list_transactions for itemized purchases. It also warns about not reconstructing totals and gives conditions for open bill availability, including connector asymmetry.

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 annotations by detailing return structure, error handling (returns object instead of throwing on 403), and a complex data integrity warning mechanism for mass zeroing. This is valuable context not captured in annotations.

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

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

The description is front-loaded with the main purpose and specific asset types, followed by error handling and data integrity details. It is reasonably concise for the complexity, though a bit lengthy. Every sentence adds value.

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

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

Given the absence of an output schema and the complexity of parameters, the description adequately covers error handling and data integrity but lacks parameter usage guidance. It is sufficient for basic understanding but incomplete for full agent autonomy.

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

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

The input schema has 0% description coverage, and the tool description does not explain parameters like item, page, type, or page_size. Only item_ids is mentioned briefly for batch support. The description fails to compensate for the lack of schema documentation.

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

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

The description explicitly states it returns the investment portfolio for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.). It clearly distinguishes from sibling tools like openfinance_list_investment_transactions by focusing on the portfolio overview rather than transactions.

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

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

The description implies usage for retrieving investment data but does not explicitly specify when to use this tool versus alternatives, nor does it provide exclusion criteria or prerequisites. The context is clear but lacks explicit 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 mark as readOnly, idempotent, and not destructive. Description adds detail on return fields (quantity, value, expenses breakdown) and the underlying operation. No contradiction.

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

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

Two short paragraphs, front-loaded with core purpose and prerequisites. No redundant information. Every sentence adds value.

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

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

Given no output schema, description explains return fields adequately. It mentions prerequisite and bulk support. Missing pagination details and explicit return type, but close to complete for a list tool.

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

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

Schema coverage is 0%, so description must compensate. It explains investment_id and investment_ids, but page and page_size are not described. Partially addresses the gap.

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

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

The description clearly states it returns movement history for investment positions, enumerates transaction types (BUY/SELL/TAX/etc.) and key fields. It distinguishes from sibling 'openfinance_list_investments' by specifying it is used after that tool to get investment_id.

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, and mentions bulk support with investment_ids. Does not give negative guidance 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.

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

Annotations show readOnlyHint=true and destructiveHint=false. Description adds behavioral details: sequential queries with rate-limit spacing, return format {results, errors} per connection. No contradiction.

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

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

Two sentences, front-loaded with purpose, each sentence adds value. 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 simple read-only list tool with one optional parameter and no output schema, the description covers parameter usage, behavior for multiple connections, and return format completely.

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%; description explains that each item is a connection selector (item_id uuid, connector_id, or connector_name), adding meaning beyond the schema.

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

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

The description clearly states the tool lists loan contracts per bank connection, using GET /loans. It distinguishes from siblings like openfinance_get_loan_detail (for a single loan) by specifying it lists loans per connection.

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 pass `items` (for specific connections) vs omit (for all banks). It also mentions sequential querying with rate-limit spacing. However, does not explicitly contrast with sibling list tools.

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

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

The annotations only say readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description does far more: it discloses connector-dependent PENDING vs POSTED behavior, sparse billId population, descending date ordering with future-dated scheduled rows, the 5000-row ceiling with truncated:true, error return shape, the account echo block, provider incidents, and auto-pagination behavior. No contradiction with annotations 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 but purposeful, with the main capability front-loaded in the first sentence. However, some details are repeated — for example, the billId predictability is explained twice, and the 5000-row ceiling is described in both aggregation and pagination sections. It could be tightened with distinct sections or cross-references to reduce 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 an 8-parameter tool, no output schema, and known connector variability, the description provides everything an agent needs to make an informed call: parameter semantics, expected response pieces (account echo, scheduled_count, notice, truncation flag), pagination behavior, error shapes, source-of-truth warnings, and cross-tool routing. Nothing critical is omitted for selecting or invoking 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%, and the description fully compensates: from/to are ISO YYYY-MM-DD date filters, search_queries is a case/accent-insensitive OR-match substring filter against description and merchant, detail is explained across compact/rich/raw with exact row-level implications, and page/page_size semantics are fully defined including defaults and max sizes. Even the bulk account_ids parameter is mentioned, and account_id is implicitly clear from the account echo narrative.

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 states exactly what the tool does: 'Returns transactions for a bank account (BANK or CREDIT type)' and immediately distinguishes credit-card transaction listing as the only way to get itemized transactions. This sets it apart from siblings like openfinance_list_credit_card_bills and openfinance_list_transactions_by_item.

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

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

The description explicitly names alternatives and selects the correct tool: use openfinance_list_credit_card_bills for standardized open-bill totals, use openfinance_list_accounts for closing/due dates, use openfinance_get_item_status for sync health, and use openfinance_force_sync for failed credit syncs. It also gives concrete pagination usage guidance, directly telling the agent to omit page/page_size for full results or pass them for manual pagination.

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 explains internal fan-out, truncation at 5000 per account with a flag, provider_incident block, and details on return format (compact vs raw). Annotations already indicate read-only, idempotent, non-destructive.

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

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

The description is well-structured and front-loaded with the primary benefit. Every sentence adds value, but it is somewhat dense; minor trimming could improve readability 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 the complexity (9 parameters, no output schema, no param schema descriptions), the description is comprehensive: it covers purpose, parameter semantics, return values, limitations (truncation), and error conditions (provider_incident). It provides everything an agent needs to correctly invoke 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?

With 0% schema description coverage, the description fully compensates by explaining each parameter: 'item' (connector_id, connector_name, or item_id), 'from'/'to' as ISO dates, granularity defaults, detail options, type filtering, top_n, and bulk via item_ids. This adds meaning that the schema alone does not provide.

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

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

The description clearly states the tool's purpose: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It distinguishes from siblings by noting that it resolves accounts internally, avoiding the need to call openfinance_list_accounts first.

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 use cases: 'Use this for 'análise anual/mensal', 'fluxo de caixa', 'entradas e saídas', 'maiores gastos/recebimentos'.' It also explains how to target one bank or all banks, but does not explicitly mention when not to use this tool or contrast with the sibling openfinance_list_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 detailed behavioral context: it checks a public status page, returns global indicator, degraded components, incidents, and flags affecting connected banks. 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 a single well-structured paragraph, front-loaded with the main purpose, and packs significant detail without verbosity.

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

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

Despite no output schema, the description fully explains the return values: global indicator, degraded components, open incidents, and affected banks. Complete for a 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?

No parameters exist, so schema coverage is trivially 100%. Baseline is 4. The description does not need to add parameter semantics.

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

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

The description clearly states the tool checks the LIVE operational status of the Open Finance provider, using specific verbs and distinguishing it from the sibling tool 'openfinance_get_item_status'.

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

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

The description explicitly says when to use this tool (when data looks incomplete or stale despite updated connection), and what it differentiates. It lacks an explicit 'when not to use' but provides strong contextual 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?

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). It explains plan-based filtering (PF vs PJ), the caveat warning for non-Open-Finance connectors, and the behavior when keywords are omitted (returns a hint instead of dumping the catalog).

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 each sentence adds value. It is well-structured, starting with the main function, then return fields, then caveats, plan behavior, usage guidance, and a note about the 'keywords' parameter. Slightly verbose but justified by the complexity.

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

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

Without an output schema, the description thoroughly explains the return values (connector id, access, audience, connections, accounts, connect_url) and special cases (caveat, plan filtering, missing keywords). This provides sufficient context for an AI agent to understand the tool's behavior completely.

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 that 'keywords' is an array of bank names (with examples) and that it's REQUIRED, despite the schema not marking it as required. It also explains 'include_accounts' as a boolean to include accounts in the response.

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

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

The description clearly states the tool searches bank connectors by name with specific keywords, and details the returned fields (connector id, access, audience, connections, accounts, connect_url). This distinguishes it from siblings like 'connect' and 'marketplace' which have different purposes.

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

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

The description explicitly advises to call this tool BEFORE connecting to provide a one-click link, and mentions preferring Open Finance connectors for automation. While it doesn't name specific alternatives, the context is clear enough for an AI agent to decide when to use it.

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 provide basic hints (readOnlyHint=false, destructiveHint=false). The description adds crucial behavioral details: it overrides automatic categorization, teaches Pluggy by creating Category Rules, details batch behavior with per-item error handling, and specifies that errors don't fail the whole batch.

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 somewhat lengthy but every sentence adds value. It is front-loaded with the main action. Slightly more structured formatting could improve readability, but it is efficient.

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

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

With no output schema and 1 parameter, the description covers all necessary context: behavior, response format (updated, results, errors), side effects, and parameter sources. It is fully complete for an agent to understand and invoke 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?

Input schema has 0% description coverage, so the description must fully explain parameters. It thoroughly describes the 'items' array structure, required fields (transaction_id, category_id), and explicitly sources these IDs from sibling tools, adding meaning beyond the schema.

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

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

The description clearly states the tool corrects transaction categories and identifies the HTTP method and resource (PATCH /transactions/:id). It distinguishes itself from sibling tools like openfinance_list_transactions and openfinance_list_categories by explaining where to get the 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?

The description explains when to use the tool (fix miscategorized transactions, improve future categorization) and mentions the side effect of creating a Category Rule. It lacks explicit statements of when not to use it, but context is clear.

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

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

Annotations provide idempotentHint=true and readOnlyHint=false, indicating it is a safe, non-destructive, and idempotent operation. The description adds value by specifying to include conversation array for reproduction but does not elaborate further on behavior beyond what annotations already convey.

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 efficiently convey purpose and a usage hint. The description is front-loaded with the core action. It is appropriately sized for a simple tool, though a slightly more structured breakdown of parameters would improve clarity.

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

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

The description lacks essential completeness: no information about the response (e.g., confirmation or ticket ID), no emphasis on the required 'message' parameter, and no explanation of the 'context' parameter. For a submission tool with no output schema, more detail is needed.

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

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

With 0% schema description coverage, the description must compensate. It only mentions the conversation parameter vaguely ('include conversation array'), but provides no details on the required 'message' parameter or the optional 'context' parameter, leaving significant ambiguity.

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 reports bugs, missing features, or sends feedback. It uses a specific verb (report) and resource (bug/feedback), and distinguishes from sibling tools which are predominantly openfinance operations, authentication, or connectivity 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 advises including the conversation array for reproduction, providing clear context on how to use the tool effectively. However, it does not explicitly state when not to use it or suggest alternatives, though sibling tools are unrelated so this is acceptable.

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 that it returns version information, but this is more about content than behavioral context. It does not disclose any non-obvious behavioral traits 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 a single, clear sentence that is front-loaded and contains no unnecessary words. Every word contributes to the purpose.

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

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

Given the simplicity of the tool (no parameters, no nested objects, no output schema), the description fully explains what the tool does and what it returns. It is complete for an agent to understand its functionality.

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

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

There are no parameters, and the schema description coverage is 100%. According to guidelines, with zero parameters, the baseline score is 4. The description does not need to add parameter semantics since 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 'Show the current MCP platform and adapter versions,' which is a specific verb+resource combination. This clearly distinguishes it from sibling tools that focus on authentication, data operations, or other functionalities.

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?

While the description does not explicitly state when or when not to use this tool, it is self-explanatory as a version info retrieval tool. The context from sibling tools makes its purpose clear, but there are no explicit exclusions or alternative suggestions.

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 read-only, idempotent, non-destructive behavior. The description adds meaningful context by specifying exactly what data the state includes (installed MCPs, connection status, accounts, catalog tool counts), which is more detailed than the annotations alone.

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 front-loads the purpose and packs all relevant details without 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?

With zero parameters, no output schema, and strong annotations, the description provides sufficient detail about the return contents. It could optionally specify the output format or structure, but the given enumeration is complete enough for a simple status tool.

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

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

The tool has zero parameters, so the description does not need to explain parameter syntax or semantics. Baseline of 4 is appropriate because there is no parameter information to compensate for.

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

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

The description clearly states the tool returns the current toolkit state, enumerating specific contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This distinguishes it from sibling tools that perform specific actions like authenticate or list accounts.

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

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

The description implies usage for obtaining an overall status overview, but gives no explicit guidance on when to use this versus alternative list tools or when not to use it. Context is clear but no exclusions or alternatives are mentioned.

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