Safra MCP

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

The description reveals that setting a permanent token in config is non-expiring, and session login is per-session. It matches annotations (idempotentHint, destructiveHint false) and adds context about the token's lifetime.

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 effectively conveys the two methods, but it could be more structured (e.g., separate bullet points) and is slightly informal.

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 explains inputs and behavior but does not describe the output (e.g., format of the returned link) or error cases. Given the simplicity, it is adequate but not fully complete.

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

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

The schema only defines 'token' as a string with no description. The description adds crucial meaning: omitting it yields a login link, including it authenticates. This compensates for 0% schema coverage.

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 (logging in) and specifies two methods: permanent via config or session via token. It targets IDE agents, but does not explicitly distinguish from sibling tools like '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 explains two ways to use the tool (with no args to get link, or with token to authenticate), but does not compare to alternative tools or indicate when to use which method.

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 meaningful context beyond annotations (readOnlyHint, idempotentHint) by explaining the different return states (authenticated vs connect_url) and the structure of pending[]. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence provides essential information without redundancy.

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

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

The description explains the return values (authenticated, pending, connect_url) sufficiently for a simple status tool, but does not cover potential error states or additional fields. With no output schema, it is fairly complete.

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

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

The tool has no parameters, and schema coverage is 100%. Baseline for 0 params is 4, and the description does not need to add parameter information.

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, with specific behavior for when all providers are connected (authenticated:true, empty pending[]) and when credentials are missing (connect_url). It distinguishes from sibling tools like `openfinance_list_connections` which likely list individual provider connections, by focusing on the overall toolkit connection state.

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

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

The description implies usage for checking overall connection status, but does not explicitly state when to use this tool versus alternatives (e.g., `authenticate` or `openfinance_list_connections`). It lacks 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?

The description goes beyond annotations by explaining the one-off execution behavior of invoke ('works even when the MCP is NOT installed'), the connect and checkout/top-up link flows, and owner/admin requirements for writes. It also clarifies the toolkit impact of install vs invoke.

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 direct and well-structured, front-loading the core purpose and using 'KEY:' to highlight the most important behavioral note. 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?

For a tool with 15 parameters and multiple actions, the description is remarkably comprehensive—covering search, describe, invoke, install, list, billing, feedback, and requests. Minor omissions like the 'resume' action and some parameter specifics prevent 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?

The schema has 0% description coverage, but the description compensates by explaining the action enum and the purpose of key parameters like action, tool_id, arguments, and mcp_id in the flow. However, it doesn't detail parameters like limit, query, message, immediate, conversation, request_name, cancel_reason, etc., so some gaps remain.

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' with a specific role: discovering and running MCPs/tools. It distinguishes itself from sibling tools by covering search, describe, invoke, install, and other actions, making its purpose unmistakable.

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: 'prefer invoke for a single/occasional use' vs 'install only to make an MCP PERMANENT'. It also details when to use list_tools, subscribe/cancel, report_bug, request_mcp, and the core search→describe→invoke flow.

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 aligns with the destructiveHint annotation by stating data is deleted and unavailable. It adds context that a re-connection URL is returned, which is useful behavioral information 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 two sentences long, front-loading the core action and effects with no superfluous 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 destructive tool with one parameter and no output schema, the description covers the primary effect and return value but omits parameter details and potential side effects, making it marginally adequate.

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

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

The schema has 0% coverage (no parameter descriptions), and the description does not explain the 'item' parameter. It only mentions 'for a specific bank', which is insufficient to understand what value to 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 explicitly states the tool revokes consent and deletes connection data for a specific bank. It is a precise verb-resource action ('disconnects a bank') and is distinct from sibling tools like force_sync or 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 explicitly say when to use this tool versus alternatives. It mentions a re-connection URL, which hints at a use case, but lacks guidance on when not to use it or prerequisites.

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

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

Annotations indicate non-readonly, non-destructive. The description adds: waits up to ~60s, polls, returns detailed status (executionStatus, lastUpdatedAt, synced). It explains needs_action with reconnect_url and timed_out behavior, and confirms no disconnect/reconnect. 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 front-loaded with the key action and use case. It structures parameter details, return values, and edge cases logically. Slightly verbose around needs_action but remains efficient and well-organized.

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

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

Covers use case, parameter options, return format (results, errors with status fields), error states (needs_action, timed_out), and follow-up actions. Despite no output schema, the description provides adequate detail for correct invocation and 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 has 0% description coverage. The description compensates fully: explains items accepts various selectors (item_id, connector_id, etc.) and that omitting it syncs all. Describes wait as boolean for synchronous vs. fire-and-forget. Adds meaningful context beyond schema.

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

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

The description clearly states the verb 'forces re-sync' and the resource 'connections'. It specifies synchronous waiting and contrasts with sibling tools like openfinance_get_item_status. The purpose is unambiguous and distinct.

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 guidance: 'when a balance or transaction list looks stale'. It explains when not to use (no disconnect needed) and provides alternatives for timeout cases (openfinance_get_item_status). Parameter wait: false for fire-and-forget is also clarified.

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

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

Annotations indicate readOnlyHint, idempotentHint, destructiveHint. The description adds beyond annotations by detailing that CREDIT accounts may return a warning without throwing, and that rows degrade to last-synced balance with realtime: false when upstream is unavailable. No contradiction.

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

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

The description is concise, packing essential information into a few sentences without redundancy. It is well-structured and front-loads 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?

Despite no output schema, the description specifies the response shape (results, errors). It covers edge cases and behavior. For a tool with one parameter and no nested objects, it is complete.

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

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

Schema has one parameter with no description. The description adds critical semantics: array of strings, size limit 1–50. With 0% schema description coverage, the description fully compensates.

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

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

The description clearly states it returns real-time balance per account id, specifies the endpoint and input parameter. It distinguishes itself from sibling tools like openfinance_get_accounts_detail and openfinance_list_accounts by focusing solely 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?

The description provides guidance on when to use the tool (get real-time balance) and explains behavior for CREDIT accounts and temporary unavailability. However, it does not explicitly mention alternatives or when not 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 already declare readOnlyHint, idempotentHint, destructiveHint. Description adds critical behavioral info: batch shape with results/errors, and the provider_incident block with a caveat about unreliable data during provider outages. This goes beyond annotations and is essential for safe usage.

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 concise, front-loaded with purpose, and covers key points in a single paragraph. Could be slightly more structured but 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?

Given no output schema, description explains return shape and provider_incident behavior. For a 1-param tool, it's fairly complete, though could clarify error handling or response format further.

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

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

Schema has 1 parameter with no description (0% coverage). Description adds meaning by constraining the array size (1–50) and mentioning batch shape, compensating for the schema's lack of detail.

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

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

The description clearly states it returns full account objects with extended creditData by id, specifying the GET endpoint and batch shape. It distinguishes from sibling tools like openfinance_list_accounts, which likely provides a list without detail.

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 an array of 1–50, implying usage when needing detailed account info. Does not mention 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds critical behavioral context: batch shape { results, errors }, Pluggy does not return paid/status field, meaning of payments[] in Brazilian Open Finance, and inconsistency of billId in transactions. No contradiction with annotations.

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

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

Description is longer but every sentence adds value. Front-loaded with main purpose, uses inline listing for fields. Could be more concise but well-organized and informative.

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 partially explains output fields and batch shape. Covers relationship to sibling tools, edge cases (paid status, billId inconsistency), and usage workflow. Very complete for a single-parameter tool.

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

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

With 0% schema coverage, description adds 'Pass bill_ids as an array' and 'use openfinance_list_credit_card_bills first to discover ids', but does not elaborate on parameter format, constraints, or examples beyond schema. Adequate but minimal added meaning.

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

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

Description clearly states 'Returns bill-level detail for one or more credit card bills by id' and lists specific fields (financeCharges, payments[]). It distinguishes from sibling openfinance_list_transactions by explicitly stating it does not return individual transactions and directs to that tool for itemized entries.

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 openfinance_list_credit_card_bills first to discover ids, pass bill_ids as array. Clear when not to use: warns against reconstructing bill total from transactions and explains that payments[] may not indicate payment of this bill. Provides alternative tool for 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 indicate readOnly, idempotent, non-destructive. Description adds value by explaining return fields (status, executionStatus, connector metadata, reconnect_url) and behavior of reconnect_url, which reopens widget in UPDATE mode without disconnecting or consuming a slot.

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 plus a line on bulk support. Front-loaded with purpose, then usage details. No redundant 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?

Covers core functionality, modes, and return fields. Lacks details on error handling, rate limits, or pagination. For a read-only status tool, it is reasonably complete.

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

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

Schema coverage is 0%, so description must compensate. It explains 'item' for single bank, 'item_ids' for bulk, but does not clarify 'item_id' parameter. Adds meaning beyond schema, but could be more precise on parameter types.

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, lists possible statuses, and distinguishes between single bank and all banks modes. It also mentions bulk support via item_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?

Provides explicit guidance on when to use 'item' for a single bank and omit for all banks, plus bulk support. However, it does not explicitly compare to sibling tools like openfinance_list_connections or give when-not-to-use conditions.

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 and idempotent. Description adds HTTP method (GET), batch shape {results, errors}, and limit of 1-50 IDs. No contradictions.

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

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

Description is dense but front-loaded with purpose; each part is useful. Could be slightly more structured, but 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 fields comprehensively (interestRates, charged fees, installments, etc.) and explains batch shape. Lacks error details but sufficient for a detail retrieval 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 has 0% description coverage. Description compensates by explaining loan_ids is an array with size constraint (1-50), adding value beyond schema.

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

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

Description clearly states it returns full loan contract detail by ID, lists many fields, and distinguishes from sibling tools by explicitly mentioning usage after openfinance_list_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?

Explicitly states when to use (after openfinance_list_loans), how to use (pass loan_ids as array 1-50), and describes batch response shape.

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, but the description adds crucial behavioral details: credit balance semantics (connector-dependent), provider_incident making values unreliable, identity_notice for joint accounts, and bulk support via item_ids. This transparency helps the agent handle data correctly.

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 primary purpose and structured logically, covering main usage, edge cases, and bulk support. While quite verbose, every sentence adds necessary context for correct usage, so it is efficient given the tool's complexity.

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

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

Without an output schema, the description thoroughly explains return values (balance, number, bank, etc.) and their meanings, including nuances like creditData fields. It also addresses error conditions (provider_incident) and deduplication guidance (identity_notice), making it fully complete for effective use.

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's purpose (item, type, item_id, item_ids) and how they affect behavior (e.g., omit item for all accounts, pass for single bank). It also details return fields like bank and connector_id, adding significant meaning beyond the raw schema.

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

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

The description clearly states the tool returns accounts for a bank connection, specifying sub-types (BANK/CREDIT) and the exact data fields such as balance, number, type, subtype, etc. It explicitly distinguishes itself from siblings like openfinance_list_credit_card_bills by noting that for standardized bill amounts, the sibling tool should be used.

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 the tool (e.g., listing accounts across all banks vs. a single bank) and when not to (e.g., for credit card bill details, it directs to an alternative). It covers Omit/pass item parameters and warns about provider_incident and identity_notice edge 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: cached per session, single aggregated response with no batch ids, and explicit field clarifications.

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

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

The description is concise and well-structured: it states the function, explains the cached nature, lists each output field with its significance, and ends with a note on the response shape. 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 zero parameters, rich annotations, and no output schema, the description adequately explains what the tool returns. It covers the fields but could briefly mention the hierarchical tree structure for clarity.

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

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

No parameters exist, so schema coverage is 100%. The description naturally does not add parameter details, meeting the baseline for zero-parameter tools.

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

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

The description clearly states it returns Pluggy's transaction category taxonomy, cached for the session. It references the endpoint and details the fields, distinguishing it from siblings by noting the id is used by openfinance_update_transaction_category.

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

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

The description implies usage before updating transaction categories, but does not explicitly state when to use or avoid this tool. It provides clear context without exclusionary 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 readOnlyHint=true and destructiveHint=false. Description adds valuable context: reconnect_url opens widget in UPDATE mode, does not consume connection slot, no need to disconnect. This goes 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?

Information-dense single sentence with good structure (colon, em-dash). All sentences are earned, though slightly lengthy. Could be more concise but well-organized.

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

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

Given no parameters and no output schema, the description explains output fields and reconnect_url behavior adequately. Does not mention pagination, but for a list of saved connections it's likely acceptable.

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 no parameters, so baseline 4. Description adds meaning about the output fields (connector_id, item_id, etc.), though this is more about return values than parameters.

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

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

Clearly states it returns saved bank connections with specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). Distinguishes from siblings by detailing the purpose of reconnect_url vs add_connection_url.

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 context on when to use reconnect_url (re-authentication, MFA, LOGIN_ERROR, stale data) but does not explicitly compare with other listing tools like openfinance_list_accounts. Usage guidance is implied but not exhaustive.

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: true, etc.), the description adds critical behavioral context: payment semantics, derived payment_status, connector asymmetry, bill grouping reliability, and return structure. No contradiction with annotations.

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

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

The description is long but well-structured with paragraphs and emphasis on key points. It front-loads the main purpose and then details nuances. Could be more concise with bullet points, but every part adds value given 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 complexity, annotations, and lack of output schema, the description is exceptionally complete. It covers return fields, derived fields, payment semantics, error conditions, cross-tool references, account echo block, and warnings about connector 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?

Schema description coverage is 0% so the description must compensate. It explains include_open_bill and account_ids in detail, but does not explicitly describe page/page_size parameters. However, the important parameters are well covered, adding significant 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 closed credit card bills for CREDIT-type accounts, listing specific fields. It distinguishes from siblings like openfinance_get_credit_card_bill (singular) and openfinance_list_transactions (for individual transactions), and specifies it is bill-level summaries.

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

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

The description provides extensive guidance: when to use include_open_bill, connector asymmetry, payment status interpretation, and directs to other tools for transactions. It explicitly states when not to assume payment status and warns about cross-bill payment semantics.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint. The description adds significant behavioral detail: error handling (returns {total,results,warning} instead of throwing), data integrity warnings for mass zeroing, and the flagging of suspect rows. 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 well-structured with a clear opening that states the purpose, followed by error handling and data integrity details. It is front-loaded but somewhat verbose in the data integrity section. Overall, it is informative without being overly long.

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 of the tool and the absence of an output schema and parameter descriptions, the description covers many aspects: asset types, response fields, error handling, and data integrity. It lacks some details on pagination parameters and the distinction between 'item' and 'item_ids', but is still quite complete.

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

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

The input schema has 6 parameters with 0% description coverage. The description only adds value for 'item_ids' (bulk support) and does not explain 'item', 'page', 'type', 'page_size', or 'item_id'. With low schema coverage, the description should compensate but fails to define most 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 returns the investment portfolio for a connection, listing specific asset types (FIIs, stocks, etc.). It distinguishes itself from sibling tools like list_investment_transactions by focusing on the portfolio snapshot.

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 mentions bulk support via item_ids and explains behavior when INVESTMENTS is not enabled (returns a warning instead of throwing). However, it lacks explicit guidance on when to use this tool versus other list tools, and does not state prerequisites or typical usage scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral detail beyond annotations: it lists transaction types, return fields (quantity, value, expenses breakdown), and bulk execution. No contradictions, and it enriches the behavioral profile.

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 in the first paragraph and a single sentence for usage guidance. Every sentence adds value: describes output, states prerequisites, and mentions bulk support. No fluff, and key information is front-loaded.

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

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

With 4 parameters, no output schema, and 0% schema coverage, the description covers the main parameter and return structure well. It omits pagination parameters but given the read-only list nature, pagination is somewhat standard. Still, a bit more detail on page/page_size would make it complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains investment_id (required) and investment_ids (bulk). However, it does not describe page and page_size parameters. While the main parameters are covered, the pagination parameters are missing, which is a 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 uses a specific verb ('Returns') and clearly identifies the resource ('movement history for a specific investment position'). It lists transaction types and fields, and distinguishes from sibling tools like openfinance_list_investments by stating it's used after that tool. This is explicit and avoids ambiguity.

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 after openfinance_list_investments to get the investment_id, providing clear sequencing context. It also mentions bulk support with investment_ids. However, it does not specify when not to use or mention alternatives, 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?

Adds value beyond readOnlyHint, idempotentHint: describes sequential per-connection execution, rate-limit handling, and return format. 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?

Three tightly written sentences. First front-loads purpose, second explains parameter, third covers alternatives and return format. No superfluous 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?

Covers core usage, parameter behavior, return format per connection. Lacks mention of potential errors or prerequisites (e.g., authentication status). Still strong for a list 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?

Schema coverage is 0%, but description fully explains `items`: array of connection selectors with three types (item_id uuid, connector_id, or connector_name) and behavior when omitted. Adds meaning far beyond empty 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?

Clearly states it lists loan contracts per bank connection with specific HTTP endpoint (GET /loans). Distinguishes from sibling tools like openfinance_list_accounts 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?

Explicitly explains when to pass `items` and when to omit for all banks. Mentions sequential querying with rate-limit spacing. Does not formally contrast with tools like openfinance_get_loan_detail, 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 and idempotentHint=true, but description adds extensive behavioral context: pagination modes (auto vs manual), error handling (returns error object instead of throwing), detail levels (compact/rich/raw) and their trade-offs, credit pending/posted behavior varying by connector, provider incident block, and warnings about billId sparsity. This goes well beyond what annotations provide.

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

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

The description is comprehensive but lengthy, spanning multiple paragraphs. While all information is valuable, it could be more structured (e.g., bullet points for parameters or pagination). However, it is front-loaded with the core purpose and maintains clarity throughout. Slightly above average given the tool's complexity.

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

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

Given 8 parameters, 0% schema coverage, no output schema, and high complexity, the description covers all necessary aspects: purpose, usage, all parameters with detailed semantics, pagination behavior, error handling, cross-references to other tools, and bulk support. 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?

With 0% schema description coverage, the description compensates fully. It explains each parameter: account_id (required), from/to (ISO YYYY-MM-DD), search_queries (case-insensitive substring match), page/page_size (auto vs manual pagination), detail (compact/rich/raw), account_ids (bulk). Default behaviors and constraints (like 5000 ceiling) are also clarified.

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 explicitly distinguishes itself by saying for CREDIT accounts it is the 'ONLY way' to get itemized transactions, differentiating it 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?

Provides explicit guidance on when to use this tool vs. alternatives: for standardized open-bill totals use openfinance_list_credit_card_bills, for statement closing/due dates use openfinance_list_accounts, and if total is 0 check connection health via openfinance_get_item_status. Also warns against summing by billId.

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

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

The description adds significant behavioral context beyond annotations: it discloses a 5000-transaction cap per account with a truncated flag, the provider_incident block for incomplete data, and the effect of granularity and detail parameters on output. Since annotations already mark the tool as readOnlyHint and idempotentHint, the description enriches transparency 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 front-loaded with the key value proposition and is well-structured, but it is somewhat lengthy due to detailed parameter explanations and multiple use-case examples. While every sentence adds value, it could be slightly more concise without losing essential 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 9 parameters and no output schema, the description provides comprehensive coverage: input semantics, output structure (compact summary fields: total entradas, saídas, saldo_liquido, por_mes, top_despesas/recebimentos, by_account), raw output details, truncation behavior, and provider incident impact. It leaves no major gaps for an AI agent to select and invoke 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?

Despite 0% schema description coverage, the description thoroughly explains all 9 parameters: item (accepts connector_id, connector_name, or item_id), from/to (ISO dates), granularity (monthly vs raw with meaning), detail (compact/rich/raw meanings), type (BANK or CREDIT), top_n, item_id, and item_ids (batch support). It also specifies defaults like granularity:'monthly' and the purpose of each enum value, fully compensating for the lack of schema descriptions.

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

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

The description clearly states that this tool provides 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It distinguishes itself from siblings like openfinance_list_accounts and openfinance_list_transactions by highlighting that it internally resolves accounts and fans out transactions, eliminating the need for separate calls. This makes the purpose specific and well-differentiated.

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 explains when to use this tool vs. alternatives, stating 'you do NOT need to call openfinance_list_accounts first nor carry account_id uuids between calls.' It provides use cases like 'análise anual/mensal', 'fluxo de caixa', and guidance on granularity ('Set granularity:"raw" to ALSO get every consolidated transaction'). It also mentions limitations (5000/account cap with truncated flag) and the provider_incident block, giving comprehensive usage context.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by detailing the output: global indicator, degraded components, incidents, and 'your_banks_affected', and noting it's live from a public page.

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 but relatively long; however, every part is relevant and well-structured. Slightly verbose but not wasteful.

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

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

Given no parameters and no output schema, the description fully explains the return value and usage context, making it 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?

No parameters exist; schema coverage is 100%, so no additional param info needed. Baseline 4 is appropriate.

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

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

The description clearly states it checks the 'LIVE operational status of the Open Finance provider', distinguishing it from the sibling 'openfinance_get_item_status' by specifying it's provider health, not connection status.

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

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

Explicitly says when to use (data incomplete/stale despite updated connection) and what it helps to discern (provider-side problem vs connection issue), with no exclusions needed.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds behavioral context: returns connector details, a connect_url, and caveat warnings for non-Open-Finance connectors. It also explains plan behavior. This goes beyond the annotations without contradicting them.

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

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

The description is comprehensive but somewhat verbose, with some redundancy (e.g., the required nature of keywords is stated twice). It could be more concise while retaining essential details.

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

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

Given no output schema and only two parameters, the description fully covers inputs, outputs, usage context, and special behaviors (caveats, plan restrictions). It leaves no obvious gaps for the agent to understand 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?

Schema coverage is 0%, but the description explains keywords (required array of strings) and include_accounts (boolean to include accounts). Since only two parameters exist, the description compensates well by providing functional meaning beyond the bare schema.

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

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

The description clearly states the tool searches bank connectors by name using a keywords array, and specifies what is returned. It distinguishes itself from siblings by mentioning it should be called before connecting, making its role unique among the sibling tools.

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

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

Provides explicit guidance: call this before connecting, keywords are required, and notes plan-dependent behavior. However, it does not explicitly mention when not to use this tool or compare with alternatives beyond the implicit context that this is the search step.

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 minimal (all false), so the description carries the full burden. It discloses that recategorizing creates a Category Rule for future similar transactions, which is a significant behavioral trait beyond the basic update. It also describes the batch error handling and output shape.

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 structured: purpose, parameter details, behavioral side effect, and error handling. A bit verbose but not wasteful.

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

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

Given one parameter (array of objects) and no output schema, the description thoroughly explains input format, side effects, and output shape. It is complete for an agent to select and invoke 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%, so the description adds full meaning. It explains that 'items' is an array of { transaction_id, category_id } and tells the agent where to obtain each ID from other tools. No additional parameters exist.

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 the category of transactions using PATCH, specifying the resource and action. It distinguishes itself from sibling tools like openfinance_list_transactions and openfinance_list_categories by focusing on updating 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?

The description explains when to use (fix miscategorized transactions) and provides sourcing for parameters (transaction_id from openfinance_list_transactions, category_id from openfinance_list_categories). It doesn't explicitly state when not to use, but the use case is specific and no alternatives are obvious among siblings.

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, conveying safety traits. The description adds no behavioral context beyond these annotations, such as whether the report creates a ticket or triggers notifications.

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 succinct with two sentences. The first delivers purpose, the second provides actionable instruction. No unnecessary words or repetition.

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 feedback tool with 3 parameters and no output schema, the description covers the basic intent and a key usage tip. However, it omits what happens after reporting (e.g., confirmation, ticket creation) and any limits or side effects.

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

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

The schema has 0% description coverage, so the burden falls on the free-text description. It clarifies the 'conversation' parameter's purpose ('recent messages for reproduction') but does not explain 'context' or 'message' parameters in any detail.

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

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

The description clearly states the tool's purpose: reporting a bug, missing feature, or feedback. It uses a specific verb ('Report') and identifies resources. While it distinguishes from financial siblings by category, it does not explicitly differentiate from other non-financial 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 instructs users to include the conversation array, which is a useful guideline for proper reproduction. However, it lacks guidance on when to use this tool versus alternatives (e.g., when not to report bugs) and does not mention any prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds specificity by naming the exact data returned (MCP platform and adapter versions), which is valuable context 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?

Single sentence of 9 words with no superfluous information. Perfectly concise and front-loaded.

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

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

Given zero parameters, no output schema, and annotations covering safety, the description fully specifies what the tool does and returns. No gaps remain.

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

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

No parameters, so schema coverage is 100%. The description correctly does not need to add parameter 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?

Description clearly states the tool shows 'current MCP platform and adapter versions' with a specific verb and resource. It distinguishes itself from siblings because no other sibling tool provides 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?

The description implies usage for retrieving version info. While no explicit when-not-to-use or alternatives are given, the tool's simplicity and lack of parameters make guidance less critical. A brief mention of when to use (e.g., 'Use to verify deployed versions') could improve it but not required.

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 confirms read-only behavior, but annotations already provide readOnlyHint and idempotentHint. No additional behavioral details (e.g., auth, rate limits) are added beyond what annotations state.

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

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

Single sentence with no waste, front-loaded with the main action verb 'Returns'.

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

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

Given no parameters and no output schema, the description sufficiently explains what the tool returns. Could mention that it is read-only, but annotations already convey that.

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 meaning. Schema coverage is 100%, meeting the baseline 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 returns toolkit state including installed MCPs, connection status, and catalog tool counts. This is a specific verb-resource combination that distinguishes it from sibling tools like show_version.

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 state inspection but does not explicitly say when to use versus alternatives like show_version or when not to use.

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