Mercado Financeiro BR

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

The description discloses the browser-based login flow and the distinction between permanent and session tokens. This adds context beyond the annotations' idempotent hint and non-destructive flag, though it doesn't detail side effects or failure modes.

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

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

The description is moderately concise but contains some redundancy and awkward phrasing ('MCP.AI for IDE agents'). The key information is present, but it could be structured more clearly.

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 auth tool, the description covers the essential usage scenarios and parameter behavior. It lacks explicit return value info but the absence of an output schema reduces the need.

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

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

The single 'token' parameter is explained as a JWT for session-only login, and the no-args behavior is described. This compensates for the schema's lack of parameter description.

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

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

The description clearly states the tool's function: logging in via browser and obtaining an access token for authentication. It differentiates from sibling tools by focusing on the auth flow, though it doesn't explicitly name alternatives.

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

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

It provides explicit guidance on two usage paths: permanent config header vs. session-only token, and explains when to call with no args to get a link. However, it does not mention alternative tools for similar purposes.

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, idempotent, and non-destructive. The description adds valuable behavioral detail by explaining the authenticated/pending fields and the connect_url scenario for missing credentials, which goes beyond the structured 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 contributes conditional detail without waste. It is highly concise and 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?

With no output schema, the description carries the burden of explaining return values. It clearly covers the fully-connected and missing-credentials cases, but does not explicitly describe partial-connection states or the structure of pending[]. That minor gap warrants a 4 rather than 5.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, and the empty schema provides complete coverage, so this score 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 the tool returns connection status and URLs, with specific conditional outcomes (authenticated:true when all connected, connect_url when credentials missing). This is a specific verb-resource pairing that distinguishes it from siblings like authenticate and marketplace.

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

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

The description provides clear context on what the tool does and when its different outputs appear, implying usage for checking connection state. However, it does not explicitly contrast with alternatives like authenticate for when not to use it, so it falls short of a 5.

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, the description reveals side effects: invoke performs a 'one-off install', returns connect/checkout links when needed, and writes require 'workspace owner/admin.' It also explains that search/describe flag installed_in_toolkit vs installed_in_workspace, and that publish_prompt yields a public link. These behavioral details go well beyond the minimal annotation hints and are crucial for safe invocation.

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

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

The description is dense but every sentence carries purpose—covering core flow, edge cases, auth restrictions, and prompt library. It is front-loaded with the main purpose, and while it is a single block of text rather than structured bullets, it avoids fluff and stays on-topic. The only slight deduction is for being overly long and not using lists to improve scanability.

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 such a complex tool (14 actions, 23 params, no output schema), the description covers a lot: core flow, invoke edge cases, auth, and prompt library. However, it omits the 'resume' action entirely, doesn't describe return formats for search/describe, and lacks explicit action-to-parameter mapping. These are meaningful gaps for an agent to correctly construct invocations, so it is 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 description thoroughly explains the action enum values (search, describe, invoke, etc.) but never maps specific parameters to those actions. For example, it doesn't say that invoke needs tool_id and arguments, describe needs mcp_id, or what immediate, conversation, or cancel_comment do. Since schema description coverage is 0% across 23 parameters, the description fails to compensate, leaving agents to guess parameter requirements for each action.

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 identifies the tool as 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It distinguishes it from siblings by outlining the core flow (search → describe → invoke) and additional prompt library features. This is a specific, action-oriented definition that separates it from tools like connect, authenticate, and report_bug.

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

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

The description gives explicit guidance: 'prefer invoke for a single/occasional use' versus 'use install only to make an MCP PERMANENT in the active toolkit.' It also spells out the core flow and lists each action's purpose, such as 'list_tools lists what is callable right now' and 'request_mcp asks us to build a NEW MCP when nothing fits.' This provides clear when-to-use and alternative direction.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the default currency behavior ('BRL por padrão'), which is useful, but does not disclose other behavioral traits such as error handling, rate limits, or response structure. With annotations covering the core safety, the added value is moderate.

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, concise sentence that front-loads the core function. It contains no redundant information and is easily parsed by an agent.

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

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

For a simple read-only tool with two parameters and strong annotations, the description covers the essential purpose and default behavior. It does not mention return format or alternative tools, but given the low complexity and annotation coverage, it is adequately complete for basic invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It provides meaning for both parameters: 'coins' are cryptocurrency symbols (BTC, ETH), and 'currency' is the chosen quote currency with a default (BRL). This adds substantial semantic value beyond the plain schema, though it does not specify formatting details like uppercase or currency codes.

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

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

The description clearly states the tool provides cryptocurrency quotes ('Cotação de criptomoedas') with examples (BTC, ETH) and the currency selection. It identifies a specific verb+resource, but does not explicitly differentiate from sibling tools like mercado_quote, so it lacks direct sibling distinction.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention when not to use it or provide context about sibling tools, leaving the agent without decision support for tool selection.

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 behavior beyond the annotations: it returns both buy and sell rates, covers specific currencies, and on weekends/holidays returns the last published bulletin. This enriches the readOnly and idempotent hints already present in annotations.

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

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

The description is two sentences, concise and front-loaded with the core purpose. It includes essential details without unnecessary filler.

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 the tool's purpose, currency scope, and fallback behavior, but leaves the input parameter format ambiguous. Without output schema or parameter guidance, an agent may struggle to invoke it correctly, though the tool's simplicity keeps it at a minimally viable level.

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 'pairs' parameter is not explained at all. The description lists supported currencies but does not specify the expected format (e.g., 'USD-BRL' vs 'USD' vs 'BRL-USD') or provide examples. With schema description coverage at 0%, the description fails to compensate for this gap.

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

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

The description clearly states it provides official closing exchange rates against the Brazilian real (BRL) for a specific list of currencies (USD, EUR, GBP, etc.), with buy and sell rates. This specific verb+resource+scope distinguishes it from siblings like mercado_crypto and mercado_quote.

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

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

The description gives clear context: this tool is for FX rates against the real, and it notes weekend/holiday fallback behavior. However, it does not explicitly mention alternative tools (e.g., mercado_crypto for crypto) or when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the 'screener' behavior (returning multiple assets) but does not disclose additional details like pagination, default limit, or return format. Since annotations are present, the description does not need to repeat safety, but it adds only minimal behavioral context beyond them.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's core purpose and capabilities. Every phrase adds value, and there is no redundancy or filler.

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 the main purpose and capabilities but lacks important context such as usage guidelines versus alternatives, the semantics of 'limit', and any indication of return format or result size. Given the tool has 6 parameters and no output schema, this is a moderate gap, making it adequate but incomplete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'busca' (search), 'filtro por tipo/setor' (type and sector filters), and 'ordenação' (sort) with examples for sort_by (variação, volume, market cap). However, it does not mention the 'limit' parameter or enumerate allowed sort_by values, leaving gaps in 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 'Lista/screener de ativos da B3' with specific asset types (ações, FIIs, BDRs), establishing a distinct purpose from sibling tools like 'mercado_quote' and 'mercado_search_ticker'. The verb 'Lista/screener' directly conveys the resource and action, making the tool's function immediately clear.

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

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

The description implies usage for listing/filtering/sorting B3 assets, but it does not explicitly state when to use this tool versus alternatives like 'mercado_quote' or 'mercado_search_ticker'. There is no 'use this for X, not for Y' guidance, so the context is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by noting that inflation also returns the last month's variation and that historical series can be daily or monthly, which is behavior beyond the annotations.

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

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

The description is a single sentence that delivers core information without redundancy, though the parentheticals make it slightly dense. It front-loads the main purpose and remains reasonably concise.

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

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

With no output schema and five parameters, the description covers the main indicator semantics and historical series option but lacks practical details such as date formats, country default, and response structure. It is adequate but incomplete for self-contained 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?

The description adds meaning to the 'indicator' parameter by defining both enum values and mentions the 'historical' option. However, it does not explain the format or purpose of 'start', 'end', or 'country', and with 0% schema coverage, these parameters remain underdocumented.

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 identifies the tool as providing official Brazilian macroeconomic indicators, specifying 'prime_rate' (Selic target) and 'inflation' (IPCA). It distinguishes from sibling tools by focusing on macro data rather than crypto, currency, or quotes, but it lacks an explicit verb like 'get' or 'fetch', making it slightly less direct.

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

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

The description implies use for Brazilian macro indicators but does not explicitly state when to use this tool over alternatives or mention exclusions. It provides context (official Brazilian macro data) but no direct guidance on when not to use it or which sibling to choose instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so basic safety is known. The description adds operational constraints like a batch limit of 20 tickers and the availability of modules for fundamental data, which adds useful context. However, it does not disclose return formats, rate limits, or behavior when optional parameters are omitted. This aligns with the calibration example where the description adds some value but not rich behavioral context.

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

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

The description is a single, dense sentence that front-loads the primary purpose (quotes for B3 instruments) and then enumerates optional capabilities. No wasted words; every clause provides relevant information. It is highly concise and 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?

The tool has 6 parameters, no output schema, and zero parameter descriptions, so the description carries a heavy burden. It covers the core function, batch limit, fundamental data modules, dividends, and price history, but does not specify defaults, parameter combinations, or response structure. This is adequate but incomplete for a tool with this 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?

Schema description coverage is 0%, so the description must compensate. It explains 'modules' as fundamental data modules (with examples), 'dividendos' as an option, and 'histórico de preços' hints at range/interval usage. However, the description does not clarify the exact role of 'range' and 'interval' beyond price history, nor the relationship between 'fundamental' and 'modules'. It adds partial meaning but leaves several parameters underspecified.

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

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

The description clearly states the tool's function: providing quotes for B3 stocks, FIIs, and BDRs in batch mode, with additional options for fundamental data, dividends, and price history. It distinguishes from sibling tools like mercado_crypto and mercado_currency by specifying the B3 equities context.

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

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

The description gives clear context for when to use the tool: for B3 equity/FII/BDR quotes, fundamental data, dividends, and historical prices. While it does not explicitly list exclusions or name alternative tools, the specificity ('B3', 'ações, FIIs e BDRs') implies when not to use it (e.g., for crypto or currency quotes). This is clear context but lacks explicit alternative references.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds little behavioral detail beyond 'Discovery rápido' and the input semantics; no return format or edge cases are described, so with annotations present this is acceptable.

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 with no repetitive or irrelevant content. It front-loads 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?

For a simple one-parameter search tool with read-only annotations, the description specifies the input, the output (the ticker), and the purpose. It omits details like multiple results or no-match behavior, but these are likely evident from the tool's design and sibling 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?

Schema description coverage is 0%, so the description must carry the parameter meaning. The phrase 'a partir de um trecho do nome/código' explains that the single required 'query' is a partial name or code, which is adequate for a single-parameter search tool.

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

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

The description uses 'Resolve o código (ticker) de um ativo a partir de um trecho do nome/código' which clearly states the tool resolves an asset's ticker from a partial name/code. This distinguishes it from siblings like mercado_quote or mercado_list, as it's a discovery/search action.

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 indicates usage for quick discovery when only a fragment of the name or code is known. It does not explicitly name alternatives or exclusions, but the purpose implicitly sets it apart from quoting or listing tools.

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

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

No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds that the conversation array is needed 'for reproduction,' which is useful context, but it does not explain side effects, output, or what happens after reporting.

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, front-loaded sentence that states the purpose and gives an actionable instruction with no repetition or fluff.

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 has 3 parameters and no output schema, the description is incomplete. It does not explain the 'context' parameter or describe what the agent should expect after reporting (e.g., confirmation, ticket ID). The conversation instruction helps, but key semantics remain ambiguous.

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 explicitly mentions the 'conversation' parameter and its purpose, but the required 'message' parameter is only implied by the word 'report,' and 'context' is entirely unexplained. This partial guidance is insufficient.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Report a bug, missing feature, or send feedback.' This distinctly sets it apart from all sibling tools, which are market-related.

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 when to use the tool (reporting issues or feedback) and gives a specific instruction to include the conversation array for reproduction. It does not explicitly name alternatives, but the sibling list makes the purpose obvious.

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 the tool as read-only, idempotent, and non-destructive. The description adds minimal behavioral context (e.g., 'current' versions) but does not disclose details like whether a network call is made or the exact output structure. This is acceptable given the safety hints, but no extra value is provided.

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

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

The description is a single, clear sentence that immediately states the tool's action and target. There is no redundant or extraneous information, exemplifying excellent conciseness.

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-query tool, the description covers the essential purpose. It doesn't specify the exact return format, but the lack of an output schema and the tool's simplicity make this minor gap acceptable. The tool is clearly a low-complexity read 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?

The tool has zero parameters, and the schema coverage is effectively 100%. The baseline of 4 applies because the description has no parameter burden. It simply states the tool's purpose without needing to explain any inputs.

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 the specific verb 'Show' and identifies the exact resources ('current MCP platform and adapter versions'), making the tool's purpose unambiguous. It distinguishes itself from sibling tools like 'toolkit_info' by focusing specifically 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?

The description implies use when version information is needed but provides no explicit guidance on when to use this tool versus alternatives. There are no exclusions or alternative tool references, though the purpose is obvious enough for a simple version query.

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 useful context about what the tool reports (connection status, accounts, catalog tool counts), implying it may check live connection state. It does not contradict annotations and goes beyond them by describing the informational content.

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

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

The description is a single, well-structured sentence that front-loads the main action and packs in all relevant output categories without unnecessary words. Every word contributes 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 simple read-only overview tool with no parameters and no output schema, the description enumerates exactly what will be returned in a way that is complete for an agent to understand its behavior. No annotations contradict, and the sibling context further clarifies its niche.

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

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

The tool has zero parameters, so a baseline score of 4 is appropriate. The description does not need to explain parameters since none exist, and the schema covers this fully.

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

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

The description uses a specific verb ('Returns') and a specific resource ('current toolkit state') with a detailed list of what that includes: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly distinguishes it from siblings like authenticate, connect, or market data 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 makes the context clear: use this tool to inspect the overall toolkit state, particularly MCP connections and accounts. It does not explicitly name alternatives or state when not to use it, but the purpose is evident enough that an agent would know this is the diagnostic overview tool.

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