Caixa Econômica Federal MCP

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

The description adds value beyond annotations by explaining the two behavioral modes (no args vs token) and the recommended permanent setup. It aligns with annotations (idempotentHint=true, readOnlyHint=false) 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?

The description is concise (3-4 sentences) and well-structured, front-loading the purpose and then detailing the two call variants without 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?

While the description covers the main behaviors, it doesn't explicitly state the return format (e.g., the link or success message). Given the simple nature and lack of output schema, it is mostly complete for correct agent usage.

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

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

The description fully explains the optional 'token' parameter: if provided, it's a JWT for session login; if omitted, it returns a login link. Schema coverage is 0%, so description compensates completely.

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

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

The description clearly states the tool is for authentication, specifying two modes: obtaining a login link or submitting a token. It distinguishes itself from sibling tools like 'connect' which are for different 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?

It provides clear context for usage: for permanent setup vs session-only login. It doesn't explicitly mention when not to use it, but the guidance is sufficient for correct invocation.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: what the return looks like in different states (authenticated vs connect_urls). It does not contradict annotations. The description adds conditional behavior details beyond the annotations.

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

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

Two sentences with no wasted words. The description is front-loaded with the main purpose and then provides clear conditional details. 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 tool's simplicity (no parameters, no output schema, clear state-based behavior), the description is complete. It covers the two main scenarios and the key outputs. No additional information 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?

There are no parameters, and schema description coverage is 100% (trivially). With 0 parameters, 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 that the tool returns connection status and URLs, and distinguishes between two states (all providers connected vs credentials missing). It mentions specific return fields (authenticated, pending[], connect_url). This differentiates it from siblings like authenticate or openfinance_list_connections.

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

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

The description explains when to expect different outcomes (all connected vs missing credentials), implying its use for checking connection status. While it doesn't explicitly name alternatives or when-not-to-use, the context from sibling tools and the descriptive scenario make usage clear. The annotations (readOnlyHint) further reinforce it's a safe, read-only check.

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=false, destructiveHint=false, openWorldHint=true. The description adds context beyond annotations: invoke may return connect/checkout links for credentials or payment, install makes MCP permanent, writes require owner/admin. 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 verbose but structured with a clear flow. It front-loads the main purpose but contains redundant phrasing (e.g., repeating 'action=search discovers'). Could be tightened without losing meaning.

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 the core workflow (search, describe, invoke) comprehensively and explains key decisions (install vs invoke). However, peripheral actions like list_tools, subscribe/cancel, report_bug, and request_mcp receive minimal detail, and no explanation of output or error handling.

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

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

Schema coverage is 0%, but the description only explains the action parameter and high-level flow. It does not detail the remaining 12 parameters (e.g., limit, arguments format, tier_slug, conversation). The agent must infer too much from parameter names alone.

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 defines the tool as 'THE official mcp.ai marketplace' for searching, describing, installing, and running MCPs. It specifies the core flow (search→describe→invoke) and distinguishes itself from siblings by being the primary catalog and runner.

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

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

Explicit guidance: 'use THIS tool FIRST' before external registries, when to use invoke (one-off) vs install (permanent), and mentions that writes require workspace owner/admin. It also differentiates list_tools for currently callable tools vs search/describe.

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

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

The description adds behavioral context beyond the destructiveHint annotation, detailing that consent is revoked, data is deleted and becomes unavailable, and an add_connection_url is returned for reconnection. 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?

Two concise, front-loaded sentences communicate the action, effect, and return value without extraneous information. Every sentence provides 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?

For a simple destructive tool with one parameter and no output schema, the description covers purpose, effect, and return value. However, it lacks parameter clarification, which is a minor gap.

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

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

The input schema has one required parameter 'item' with no description (0% schema coverage). The tool description does not explain what 'item' refers to, leaving ambiguity. For a tool with one parameter, the description should clarify it, e.g., bank 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, specifying the action (revokes/deletes), resource (bank consent/connection), and consequence (data unavailable). It distinguishes from siblings like openfinance_list_connections which only list connections.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives such as openfinance_list_connections or connect. No when-to-use or when-not-to-use conditions are mentioned.

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 mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that it may take ~60s, polls until done, can be fire-and-forget, and explains possible outcomes like needs_action and timed_out. 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 long paragraph but front-loaded with main action, use case, parameters, then return format. It is efficient but could be slightly more structured. No wasted words.

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

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

No output schema, but description covers return format with fields like status, executionStatus, lastUpdatedAt, synced, needs_action, timed_out. It differentiates from sibling tools and addresses complexity.

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. The description fully explains both parameters: 'items' as selectors or omitted for all, 'wait' boolean with behavior details. Adds significant meaning.

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

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

The description clearly states the tool forces a bank to re-sync connections and waits for completion. It uses specific verb 'force sync' and resource 'connections', and distinguishes 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 says when to use: 'when a balance or transaction list looks stale'. It also advises against disconnecting/reconnecting and provides alternative for timed_out 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description explains that CREDIT accounts may return a structured warning instead of throwing and gives the response shape. This adds valuable behavioral context such as non-exceptional error 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 efficiently convey purpose, parameter usage, and special behavior. No extraneous information; every sentence adds value. The structure front-loads the main action.

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 single-parameter tool with no output schema, the description covers the main behavior and error handling. However, it lacks details on the balance payload fields (e.g., available, current balance) which could help the agent use the results. Still, it provides the overall response shape, making it fairly complete.

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

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

With 0% schema description coverage, the description fully compensates by explaining the parameter: an array of account IDs with a constraint of 1-50 items. This adds essential semantic meaning that the schema alone lacks.

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

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

The description clearly states the tool returns a real-time balance payload per account ID, specifying the HTTP method and endpoint. It unambiguously distinguishes from sibling tools like list_accounts and get_accounts_detail by focusing on balance retrieval.

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

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

Provides explicit guidance on passing account_ids as an array of 1-50 items. Describes error handling for CREDIT accounts. However, it does not explicitly mention when not to use this tool or suggest alternatives among siblings, leaving some room for improvement.

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, and destructiveHint. Description adds operational details: batch return shape with results/errors, array size limit, and inclusion of creditData. 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, no filler, front-loaded with the core action and resource. Every word earns its place.

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

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

For a low-complexity tool with one parameter and no output schema, the description covers input constraints, output shape, and data content (creditData). Complete and 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?

Schema coverage is 0%, but description adds meaning by specifying that account_ids must be an array of strings with length 1-50, and that each string is an account ID. This compensates for 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?

Clearly states the verb (returns) and resource (full account objects with extended creditData) per ID. Distinguishes from sibling tools like openfinance_list_accounts by specifying that it returns detailed objects for specific IDs in 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?

Specifies input constraints (array 1-50) and batch output shape, but does not explicitly state when to use this tool vs openfinance_list_accounts or other siblings. No exclusion criteria or alternative usage 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds critical context: Pluggy does not return a paid/status field, payments[] reflects previous bill's payment, and suggests openfinance_list_credit_card_bills to check payment status. 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 fairly long but well-structured: purpose, exclusions, usage instructions, and important notes. Every sentence adds value. Slightly verbose but justified by 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?

Despite no output schema, the description explains return shape ({results, errors}), lists fields in payments, and warns about Brazilian Open Finance nuances. It fully equips the agent to use the tool correctly, including prerequisites and limitations.

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?

Only one parameter (bill_ids) with 0% schema coverage. The description explains that bill_ids should be an array obtained from openfinance_list_credit_card_bills first. It adds meaningful context beyond the schema, though it does not detail the format of individual IDs.

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

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

The description explicitly states the tool returns bill-level detail (financeCharges, payments) by ID, distinguishing from openfinance_list_transactions which returns individual transactions. It also mentions batch shape and endpoint. Very clear verb+resource scope.

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: use openfinance_list_credit_card_bills first to discover ids, and use openfinance_list_transactions for itemized transactions. It warns about Pluggy not returning paid status and clarifies the meaning of payments[]. Full decision support.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds value by detailing return values and two modes of operation. 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, front-loaded with key information, no redundant words. Efficient and 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 one param and no output schema, the description covers all needed semantics: status values, return structure for both modes, and parameter behavior. Complete for the tool's simplicity.

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

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

The only parameter 'item' has 0% schema description coverage, but the description fully explains its optionality and the effect of omitting versus including it, including return shape differences.

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

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

Description explicitly states it returns bank connection status with enumerated states (UPDATED, UPDATING, LOGIN_ERROR) and distinguishes two modes (all banks or single bank). Clearly differentiates from sibling tools like openfinance_list_connections.

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

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

Provides clear guidance on when to omit vs provide item parameter. Does not explicitly state when not to use or name alternative tools, but the context is well-defined.

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 essential behavioral context: credit card balance meaning is connector-dependent and should not be treated as this month's bill, plus clarifies open billing cycle 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?

The description is well-structured and front-loaded with the most important information, but it is quite long. However, every sentence adds value, so it earns its length.

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 fields (bank, connector_id, item_id, balance meaning) and caveats. It also references a sibling tool for more standardized credit card billing data, ensuring 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 description adds significant meaning beyond the schema: it explains the optional 'item' parameter for targeting a single bank versus all banks, and the 'type' parameter for filtering by account type. The schema only provides type as enum and item as string without descriptions.

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

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

The description clearly states it returns accounts for bank connections with specific types (BANK and CREDIT) and fields such as balance, number, type, subtype, bankData, and creditData. It effectively distinguishes from sibling tools like openfinance_list_credit_card_bills.

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

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

Explicit guidance on when to omit or include the 'item' parameter: OMIT to list all accounts across banks, PASS to target a single bank. Also contrasts with openfinance_list_credit_card_bills for credit card bill amounts.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true; description adds caching behavior, response structure, and single aggregated nature, providing 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?

Three clear sentences front-loading purpose. Efficient but could combine last two sentences. 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?

Fully describes a simple list tool with no parameters. Covers output fields, caching, and relationship to sibling tool. No gaps given the tool's simplicity 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?

No parameters defined, baseline score 4. Description adds meaning to output fields (id, description, descriptionTranslated, parentId, parentDescription), which is helpful since no output schema exists.

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

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

Clearly states the tool returns the transaction category taxonomy with verb 'Returns' and resource 'category taxonomy'. Mentions caching and structure. Distinguishes from siblings by specifying 'single aggregated response'.

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?

Implies usage via mentioning categoryId for update tool, but no explicit when-to-use or when-not-to-use. No alternatives listed.

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 destructiveHint=false. The description adds behavioral context by listing the return fields and mentioning an add_connection_url, but it does not disclose potential side effects, auth requirements, or rate limits. 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 a single sentence that efficiently conveys the tool's purpose and output without any wasted words. It is front-loaded with the action and resource.

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

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

Given zero parameters, no output schema, and adequate annotations, the description is complete enough for an agent to understand the tool's functionality. It explicitly lists return fields and the add_connection_url, which is sufficient context for this simple 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?

The input schema has zero parameters, so the baseline is 4. The description adds value by specifying what the output contains, but no parameter documentation is needed. Schema description coverage is 100%.

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

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

The description clearly states the tool returns saved bank connections for the install, specifying the exact fields (connector_id, item_id, bank name, add_connection_url). It distinguishes itself from sibling tools like openfinance_disconnect_bank and openfinance_get_item_status by focusing on 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 implies the tool is used to retrieve saved connections, but it does not provide explicit guidance on when to use it vs. alternatives (e.g., before adding a new connection or checking existing ones). No exclusions or when-not-to-use are mentioned.

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 and idempotentHint. The description adds extensive behavioral context: payment status derivation logic, connector asymmetry, the optional open_bill feature, and a warning about not assuming payments mean the bill is paid. No contradictions.

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

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

The description is very long and dense, packing a lot of information. While all details are valuable, it could be more structured with bullet points or clearer sections. It is front-loaded with the main purpose, but the length may overwhelm.

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 (derived payment_status, connector asymmetry, optional open_bill) and absence of an output schema, the description is remarkably complete. It covers return fields, edge cases, limitations, and fallback behavior, leaving no obvious 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 coverage is 0%, so the description must compensate. It explains include_open_bill in detail (default, behavior, performance trade-off) and mentions account_ids for bulk. However, page and page_size pagination parameters are not explicitly explained, though their purpose is somewhat implied. Slight gap.

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

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

The description clearly states the verb (returns), resource (closed credit card bills), and scope (for a CREDIT-type account). It distinguishes from sibling tools like openfinance_list_transactions by specifying that this returns bill-level summaries, not individual 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 explicitly tells when to use this tool (to get closed bills and derived payment status) and when not (for itemized purchases, use openfinance_list_transactions). It also explains when to opt-in for open bills and warns about 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?

Annotations indicate readOnly=true, idempotent=true, destructive=false. The description adds that it returns a specific warning structure on errors rather than throwing, and lists many returned fields, providing behavioral context beyond annotations. No contradictions.

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

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

The description is a single sentence that conveys key information efficiently, front-loading the main action. It could be slightly improved with structured formatting, but is not overly verbose.

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

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

The description covers many output fields and error handling, but is missing explanations for parameters and pagination. Given the complexity and no output schema, more detail on parameters would improve 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?

Schema description coverage is 0%, and the description does not explain any of the 4 parameters (item, page, type, page_size). Their purpose is not clarified, so the description fails to add value beyond the schema.

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

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

The description clearly states it returns the investment portfolio for a connection, listing specific asset types and fields, distinguishing it from sibling tools like openfinance_list_accounts and openfinance_list_investment_transactions.

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

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

The description includes behavior on error (returns a structure instead of throwing), implying safe usage when investments are not enabled. However, it does not explicitly compare to alternative tools or specify when to use this tool versus others.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing the returned fields (quantity, value, amount, netAmount, agreedRate, brokerageNumber, expenses) and transaction types. It does not explain pagination behavior or default sorting, but overall transparency is good.

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 paragraph that front-loads purpose, then details fields, usage prerequisites, and bulk support. Each sentence adds value without redundancy. It could be structured more explicitly, but it is concise 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?

Given read-only annotations and no output schema, the description fairly explains the return content (fields per row) and usage context (prerequisite tool). Missing details on pagination behavior and ordering of results, but overall sufficient for a read-only operation.

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 for parameter guidance. It covers investment_id (use after get investments) and investment_ids (bulk support) but omits any explanation for page and page_size parameters, which are part of the schema. This leaves two of four parameters undocumented.

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

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

The description clearly states the tool returns movement history for a specific investment position, listing transaction types (BUY/SELL/TAX/INTEREST/AMORTIZATION/TRANSFER) and key fields. It distinguishes itself from sibling tools like openfinance_list_investments, which lists investments rather than their 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 explicitly states to use the tool 'after openfinance_list_investments to get the investment_id,' providing clear prerequisite context. It also mentions bulk support for batched execution via investment_ids. However, it lacks explicit guidance on when not to use or alternatives, though the sibling tools are distinct.

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), the description adds that queries are sequential with rate-limit spacing, and returns `{ results, errors }` per connection. 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?

Two sentences cover purpose, parameter usage, and behavior with no extraneous text. Front-loaded with key 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?

For a tool with one optional parameter and no output schema, the description is complete. It explains both usage modes (with/without items), rate limiting, and return structure, sufficient 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?

The schema has 0% description coverage for the `items` parameter, but the description fully explains its format (array of connection selectors: item_id uuid, connector_id, or connector_name) and behavior (one per connection). Adds significant meaning beyond the schema.

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

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

The description clearly states 'Lists loan contracts per bank connection (GET /loans)', specifying verb, resource, and scope. It distinguishes from sibling list tools by focusing on 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?

It provides clear guidance on using `items` vs omitting it, and mentions rate-limit spacing. However, it does not explicitly compare to alternative tools like openfinance_list_accounts, though the purpose 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 (readOnlyHint, idempotentHint), the description discloses auto-pagination with 5000 ceiling, truncation warning, error handling returning warning/error instead of throwing, credit card pending/posted variation by connector, and detail level trade-offs. 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?

While the description is lengthy (several paragraphs), it is well-structured: general purpose, credit card specifics, pagination, detail options, error handling, and troubleshooting. Front-loaded with key info. Some redundancy could be trimmed, but overall efficient for the complexity.

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

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

Given the tool's complexity (8 parameters, credit card intricacies, multiple detail levels, pagination, error handling) and no output schema, the description covers all necessary aspects. It explains return values (auto-paginated list), edge cases (truncated, zero results), and even suggests checking connection health via openfinance_get_item_status. 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?

With 0% schema coverage, the description explains all 8 parameters: from/to date formats, page auto vs manual, detail enum meanings (compact/rich/raw with examples), search_queries semantics (case-insensitive substring, OR), and account_ids for bulk. Each parameter's effect and usage is fully described.

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 transactions for bank accounts of type BANK or CREDIT. It distinguishes credit card transactions as the only way to get itemized data and links to sibling tool openfinance_list_credit_card_bills via billId. The verb 'Returns' and resource 'transactions' are specific and 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?

Explicitly states when to use (for credit card itemized transactions) and when not to (use openfinance_list_credit_card_bills for total debt, openfinance_list_accounts for closing/due dates). Provides alternative tool names and explains the relationship between them, e.g., 'To get a standardized open-bill total / total debt regardless, use...'.

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, and destructiveHint. The description adds valuable behavioral details: scan caps at 5000/account with a truncated flag, internal account resolution, and the effect of granularity/detail on output richness. No contradictions.

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

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

The description is relatively long but every sentence is informative. It front-loads the main purpose and benefit, then details parameters and use cases. Could be slightly more concise, but for the complexity it is well-structured.

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

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

Given 7 parameters, no output schema, and rich behavioral details, the description is highly complete. It covers output structure (compact summary vs raw rows with optional enrichment), truncation behavior, and parameter combinations. No significant 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 coverage is 0%, so the description fully compensates. It explains each parameter: item (connector_id/name or omission), from/to as ISO dates, granularity (monthly/raw), detail (compact/rich/raw), type (BANK/CREDIT), and implicitly top_n via 'largest N'. All parameter meanings are clear.

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 provides consolidated cash-flow analysis for a bank connection over a period in one call, distinguishing it from sibling tools that require separate account listing. The description specifies it resolves accounts internally, avoiding multiple calls.

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 gives use cases ('análise anual/mensal', 'fluxo de caixa', 'maiores gastos/recebimentos') and explains when to use compact vs raw granularity. Also tells the agent it does NOT need to call openfinance_list_accounts first, and that omitting the item parameter analyzes all linked banks.

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, but the description adds significant value by detailing what the tool returns: global indicator, degraded components, open incidents, and affected banks. 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?

The description is appropriately sized with three informative sentences. It is front-loaded with the main purpose, though slightly verbose but 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?

Despite lacking an output schema, the description comprehensively explains the return values: global indicator, degraded components, open incidents, and affected banks. This is sufficient for the agent to understand the tool's output 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?

The tool has no parameters, so the baseline is 4. The description is not required to add parameter info beyond the schema, which already has 100% coverage 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?

The description clearly states it checks the LIVE operational status of the Open Finance provider, distinguishing it from the sibling tool openfinance_get_item_status. It uses specific verbs and identifies the exact resource (provider's health).

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

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

The description explicitly tells when to use this tool: 'whenever data looks incomplete or stale even though a connection shows UPDATED', and it contrasts with openfinance_get_item_status, providing clear 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 mark it as read-only and idempotent. The description adds context: returns caveat warnings for credential connectors, honors plan, and returns a hint when keywords are omitted. 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?

Every sentence adds value; no fluff. Front-loaded with purpose, then details. Length is appropriate for the complexity.

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

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

Without output schema, the description fully describes return fields (connector id, access, audience, connections, accounts, connect_url, caveat). Also covers edge cases (no keywords, plan limitation).

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

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

Despite 0% schema description coverage, the description thoroughly explains both parameters: keywords (with examples) as required, and include_accounts (affects returned account data). It even overrides schema's 'required: false' by stating keywords is REQUIRED.

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 specific verb 'Searches' and resource 'bank connectors', and clearly lists all returned fields. It distinguishes itself from siblings like connect and list_connections by stating it provides a ready connect_url and should be called before connecting.

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

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

Explicitly states 'Call this BEFORE connecting' and describes when to use (to find the right bank) and when not to (never dumps whole catalog). Also explains plan behavior and caveat handling.

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 are basic, but description fully discloses side effects overrides automatic categorization, teaches via Category Rules, and details batch error handling per-item errors don't fail batch. 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?

Description is well-structured and front-loaded, but slightly verbose; could trim redundant phrases like 'Pass items as an array...'. Nonetheless, every sentence serves a 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 no output schema, description provides complete response shape, explains side effects, error handling, and parameter semantics. Leaves no important gaps for agent to infer.

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

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

With 0% schema coverage, description compensates fully: explains items array structure, required fields (transaction_id, category_id), their provenance, and even provides response shape. Adds high value beyond sparse 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 corrects transaction categories via PATCH /transactions/:id, identifies specific resources (transaction_id, category_id), and distinguishes from sibling tools like openfinance_list_transactions and openfinance_list_categories.

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

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

Provides clear guidance on when to use (fix miscategorized transactions, improve accuracy) and where to source IDs. Implicitly warns of side effects creating Category Rules but lacks explicit when-not-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 indicate idempotentHint=true and destructiveHint=false. Description adds that the conversation array aids reproduction, but does not disclose response behavior or potential 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 sentences, front-loaded with purpose, no filler. 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?

Adequate for a simple reporting tool, but lacks explanation of the 'context' parameter and does not describe expected response. With no output schema, more detail would help.

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%. Description mentions 'conversation array' should contain recent messages, adding some meaning to that parameter. However, 'context' and 'message' 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?

Description clearly states the tool reports bugs, missing features, or feedback. It is distinct from sibling tools which are finance-related, authentication, or utility tools.

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

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

Provides guidance to include the conversation array for reproduction, but does not specify when not to use or contrast with alternatives. No sibling tool serves the same purpose.

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 and idempotentHint. The description adds the specific content (platform and adapter versions) beyond the generic 'version', but no additional behavioral traits are disclosed.

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, concise and front-loaded. Every word is 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?

For a simple version retrieval tool with no parameters, the description is complete. No output schema needed; the purpose is clear.

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

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

No parameters exist, so the description does not need to add param info. Baseline 4 for zero parameters is appropriate.

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

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

The description clearly states it shows current MCP platform and adapter versions, using a specific verb and resource. It distinguishes from siblings like toolkit_info by focusing on version information.

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

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

No guidance on when to use vs. alternatives. Given siblings like toolkit_info may overlap, the description does not clarify the context for using this tool over others.

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

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

Annotations provide readOnlyHint, idempotentHint, destructiveHint false. Description adds specific behavioral details: what is returned (installed MCPs, connection status, catalog count). No contradictions.

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

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

Single sentence, directly informative, front-loaded with key action. 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?

Tool is simple with no input parameters and no output schema. Description fully conveys the return content. 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?

No parameters. Schema coverage is 100% (zero params). Description adds no parameter info because none exist. Baseline 4 for 0 params.

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?

Clear verb+resource: 'Returns the current toolkit state'. Specifies exactly what is returned (installed MCPs, connection status, catalog tool counts). Distinct from all sibling tools, which focus on authentication, marketplace, or openfinance operations.

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

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

Description implicitly indicates use when toolkit state is needed. No explicit when-not or alternatives, but the tool is simple and no-parameter, so guidance is adequate. Annotations already confirm read-only, adding no extra usage direction.

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