Tabela FIPE

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

Annotations indicate idempotent=true, destructive=false, readOnly=false. Description adds details about token handling and link generation. No contradictions. Could mention rate limits or token validation, but sufficient.

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

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

Two sentences, front-loaded with context. First sentence is slightly long but packs useful info. Could be more structured with bullets, but 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 the tool's simplicity and no output schema, description covers essential scenarios. Lacks error handling or token validation details, but complete enough for an agent to use 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 has one parameter 'token' with 0% description coverage. Description fully explains its meaning and usage (JWT token from browser login). Compensates perfectly for schema 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 handles authentication for MCP.AI IDE agents. It specifies three distinct scenarios (permanent config, session paste, no-args link). It differentiates from siblings implicitly as no sibling is authentication-focused, but does not explicitly contrast with '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?

Explicitly describes three usage modes with context: permanent config, session-only paste, and calling with no args to get a link. Does not explicitly state when not to use, but covers main use cases adequately.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations by explaining the two possible outputs (connected vs missing credentials) and the URLs returned. 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 two sentences, front-loading the core purpose and then detailing edge cases. Every sentence adds value with 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?

Given no parameters, no output schema, and sufficient annotations, the description completely covers the tool's behavior. It explains the two return scenarios clearly.

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 need not explain them. Schema coverage is 100% (none). Baseline 4 for zero parameters is appropriate.

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

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

The description clearly states the tool's purpose: returning connection status and URLs. It distinguishes between two states (all connected vs missing credentials) with specific details (e.g., authenticated:true, pending[] empty, connect_url). This is specific and distinctive.

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 connection status but does not explicitly state when to use this tool versus siblings like 'authenticate' or other tools. No exclusions or alternative guidance is provided.

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 readOnly and idempotent. Description adds return format and example, enhancing transparency beyond annotations.

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

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

Two concise sentences, front-loaded with action and output format. 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?

Partially explains output and links to next tool, but lacks parameter details and overall flow context given no output schema.

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

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

Schema coverage is 0%, yet description gives no parameter descriptions. Parameter names are somewhat self-explanatory, but the description fails to compensate for the lack of schema documentation.

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

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

Description clearly states it lists model-years with fuel for a model, with an example and direction to fipe_preco. It distinguishes from sibling FIPE tools but does not explicitly connect to the required parameters.

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

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

Specifies to use the result in fipe_preco, providing clear context. No exclusions or when-not-to-use guidance, but sufficient for a sequential workflow.

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, covering safety. The description adds that the search is fuzzy and returns a list of candidates, which is mildly behavioral but not extensively beyond annotations.

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

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

The description is a single sentence with a helpful example, making it concise and to the point. It is appropriately sized but could be slightly more structured with separate lines for clarity.

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

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

Given two parameters and no output schema, the description provides a reasonable overview of purpose and return structure. However, it lacks detailed parameter explanations and does not specify query syntax or constraints, leaving gaps for an agent to infer.

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

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

The input schema has 0% description coverage and the tool description does not explain the parameters 'q' or 'tipo_veiculo' explicitly. The example hints at 'q' being a model name, but no types or formats are mentioned, leaving the agent without sufficient guidance.

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 a fuzzy search by model name, provides examples, and indicates it returns candidates for subsequent queries. However, it does not explicitly differentiate from sibling tools like fipe_modelos, which might also list models.

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 this is a preliminary step before fipe_anos or fipe_preco, giving some usage context. But it lacks explicit when-to-use or when-not-to-use guidance, or mention of alternatives like fipe_marcas.

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, so the description adds value by specifying the return format (list of objects with referencia, mes, valor) and ordering (oldest to newest). There is 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 consists of two concise sentences. The first defines the tool's purpose and value proposition, and the second specifies the return format and ordering. No unnecessary information is included.

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 (3 parameters, no output schema), the description is incomplete: it does not explain input parameters or clarify how to use them. It also does not differentiate usage from sibling tools like 'fipe_preco' or 'fipe_buscar'.

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, and the tool description does not explain any of the three parameters (codigo_fipe, ano_modelo, combustivel). This is a significant gap as the description fails to add meaning beyond parameter names.

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

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

The description clearly states the tool returns a time series of vehicle prices over reference months, specifically calling it a 'depreciation curve' and distinguishing it from consulting the website. It uses a specific verb ('retorna') and defines the resource (historical prices).

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 historical price data versus current price tools like 'fipe_preco', but does not explicitly state when to use this tool over siblings. No exclusions or alternative recommendations are provided.

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 readOnly, idempotent, and non-destructive. Description adds return format and role in workflow, but no additional behavioral traits beyond what annotations imply.

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 that efficiently convey purpose, parameter, output, and context without any wasted words.

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

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

Tool has low complexity (1 param, no output schema). Description sufficiently explains input, output, and its place in the workflow.

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% coverage, but description fully explains the sole parameter (tipo_veiculo) with mapping to vehicle types, compensating completely.

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

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

Description clearly states it lists brands for a vehicle type with specific codes (1=carro, 2=moto, 3=caminhão) and return format. Distinguishes from sibling tools like fipe_modelos and fipe_preco.

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?

States it is the first step of a drill-down to price, implying when to use it. However, does not explicitly exclude alternatives or provide when-not 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, idempotentHint, and destructiveHint. The description adds the return format but no additional behavioral context beyond what annotations imply, earning a baseline score.

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 extremely concise with no superfluous words, front-loading the key action and output format in two sentences.

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

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

While the tool is simple and annotations cover safety, the description omits parameter semantics and lacks an output schema. The return structure is mentioned but insufficient for a complete understanding.

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 zero description coverage, and the description does not explain the purpose or possible values of the two parameters, especially tipo_veiculo, leaving the agent without critical 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 that the tool lists models for a brand, specifies the return structure, and references the prerequisite tool fipe_marcas, making the purpose unambiguous.

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

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

It provides explicit guidance to use the codigo_marca from fipe_marcas, establishing a clear dependency. However, it does not explain when not to use this tool or suggest alternatives for similar functionality.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds value by detailing the two ways to identify the vehicle, the default for referencia, and the return object structure, which goes 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 concise, consisting of two sentences in Portuguese. It front-loads the purpose and efficiently covers identification methods, default behavior, and return format without wasted words.

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

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

Given the tool has 7 parameters, no output schema, and no enums, the description is fairly complete. It explains both identification methods, the optional referencia parameter, and the return object structure. However, it does not mention error cases or constraints like the format of codigo_fipe.

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 by explaining two identification methods: using codigo_fipe or a tuple of five parameters (tipo_veiculo, codigo_marca, codigo_modelo, ano_modelo, combustivel). It also clarifies that referencia is optional and defaults to the current month. However, it does not provide individual parameter types or constraints.

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 states 'Preço de referência FIPE de um veículo' (FIPE reference price of a vehicle), which uses a specific verb and resource. It clearly distinguishes from sibling tools like fipe_anos, fipe_historico, etc., by specifying that this tool retrieves the current reference price.

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 identification methods and the default for referencia, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., fipe_historico for historical prices) or when not to use it. The context is clear but lacks exclusions.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the date range (~2001→hoje), the return structure with fields (codigo, mes, is_current), and the meaning of is_current. 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 two sentences, front-loaded with purpose, then return format and usage. Every sentence adds value without waste.

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 is complete. It explains what the tool does, what it returns, and how to use it with sibling tools. No missing information.

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 baseline is 4. The description adds meaning beyond the schema by explaining the return format and how the output is used, which is sufficient.

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

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

The description clearly states the tool lists reference months of the FIPE table from ~2001 to today, and specifies the return format. It distinguishes itself from siblings by explaining how its output (codigo) is used as a parameter in other tools like fipe_preco and fipe_historico.

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

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

The description explains when to use the tool (to get reference months for price queries) and how to use its output (use codigo as referencia in other tools). While it does not explicitly list when not to use it, the context is clear and sufficient for an agent to decide.

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

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

The description discloses several behavioral traits beyond the annotations, including that 'invoke works even when the MCP is NOT installed — it runs the tool pontualmente,' returns connect/checkout links when credentials or payment are needed, and requires workspace owner/admin for writes. It also mentions the distinction between installed_in_toolkit vs installed_in_workspace, providing important context not available from 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?

Despite being a long paragraph, every sentence adds meaningful information with no redundancy. It is front-loaded with the core definition and flows naturally through the main actions, key caveats, and the prompt library sub-feature. The density is justified given the tool's complexity and the need to cover 14 actions and multiple edge cases in a single description.

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 very complex meta-tool with 23 parameters and no output schema, the description provides a remarkably complete picture. It covers the core flows, special cases (uninstalled MCPs, payment/auth requirements), permission requirements, and sub-capabilities (prompt library). It goes beyond the structured data to explain exactly what the tool can do and how it behaves in different contexts, making it nearly self-sufficient.

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

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

With 0% schema description coverage, the description must compensate for explaining parameters. It effectively does so by describing the 'action' parameter's values (search, describe, invoke, etc.) and their semantics, and clarifies related parameters like mcp_id, tool_id, arguments, and prompt_vars. However, not all 23 parameters are explicitly mapped (e.g., limit, immediate, tier_slug, cancel_reason), so while it covers the core ones well, there is a slight gap in exhaustive parameter guidance.

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 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' giving a specific verb ('catalog' and 'run') and resource (MCPs/tools). It distinguishes itself from sibling tools like fipe_* by focusing on marketplace operations rather than domain-specific queries. The multi-action nature is explicitly outlined, removing ambiguity about its purpose.

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

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

The description provides explicit when-to-use guidance, such as 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT in the active toolkit.' It also contrasts with alternatives like list_tools ('lists what is callable right now') and describes the core search→describe→invoke flow. It covers when to use subscribe/cancel, report_bug, request_mcp, and prompt library functions, making it clear when this tool should be selected over 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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false) suggest a safe, repeatable write operation. The description adds the detail to include conversation for reproduction, which is helpful but not extensive 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?

Two sentences with clear, front-loaded purpose. No unnecessary words. Every sentence earns its place.

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

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

Given no output schema and three parameters (one required), the description covers purpose and one param but omits details on 'context' and return behavior. Adequate but with gaps.

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

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

Schema coverage is 0%, so description must compensate. It explains the 'conversation' parameter's role for reproduction but does not describe 'message' (required) or 'context'. Thus, partial coverage only.

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 is for reporting bugs, missing features, or feedback. It distinguishes from sibling tools, none of which handle bug reporting.

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

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

The description advises to include the conversation array for reproduction, providing context for use. It does not explicitly state when not to use or compare to alternatives, but as the only bug tool, exclusions are less critical.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds that it shows versions, but no additional behavioral traits beyond what annotations imply. Adequate given 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, 10 words, front-loaded. No unnecessary 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 zero parameters, no output schema, and annotations covering safety, the description fully conveys what the tool does. No gaps.

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

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

Zero parameters, so description does not need to explain param semantics. Baseline score of 4 applies.

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 uses specific verb 'Show' and specifies resource 'current MCP platform and adapter versions'. Clearly distinguishes from sibling tools like authenticate or fipe_buscar.

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?

Implicitly clear when to use (need version info), but no explicit guidance on when not to use or alternatives. However, with no parameters and simple purpose, this is sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value by specifying what the state includes, providing context beyond the raw annotation hints. It doesn't contradict annotations and gives useful behavioral expectations about the return 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 action ('Returns') and then lists the key items in the returned state. It is concise with no filler words or 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 simple no-parameter introspection tool, the description fully covers the tool's scope. It explains the return content comprehensively (installed MCPs, connection status, accounts, tool counts), which suffices in the absence of an output schema. The annotations and empty schema complete the context.

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

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

The input schema has no parameters, so the description doesn't need to explain parameter syntax. With zero parameters, the baseline is 4, and the description appropriately focuses on the return value. No additional parameter guidance is necessary.

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

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

The description clearly states the tool 'returns the current toolkit state' and enumerates specific contents: installed MCPs, connection status, accounts, and catalog tool counts. This is a specific verb+resource that distinguishes it from siblings like connect/authenticate (which establish connections) and show_version (which reports 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 the tool is for inspecting toolkit state, but it does not explicitly state when to use it versus alternatives (e.g., 'use this to check connection status instead of reconnect'). The context from sibling names suggests a use case, but the description itself lacks direct guidance on when/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.