Mercos

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

Annotations already provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false, which the description does not contradict. The description adds context about the distinction between permanent (config-based) and session-only authentication, and explains that calling with no args returns a link, enriching the behavioral model 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 appropriately sized for the complexity, covering multiple auth modes without fluff. It front-loads the core purpose and then details the token and no-arg behaviors. While a bit dense, every sentence contributes necessary information, so it earns a high score.

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 tool with one optional parameter and no output schema, the description is complete. It explains the main purpose, the two authentication methods (permanent config vs. session token), and the no-arg behavior, leaving no critical gaps for an agent to invoke it correctly.

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

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

With 0% schema description coverage, the description fully compensates by explaining the token parameter's usage: call with { token: "<jwt>" } after paste, and that omitting it yields the link. This gives clear meaning to the otherwise bare schema and clarifies optionality.

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's purpose: to authenticate to MCP.AI for IDE agents, with a clear verb ('authenticate') and resource (MCP.AI server). It differentiates from sibling tools by detailing the login flow and token-based session/permanent authentication methods, making its scope 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?

Provides explicit when-to-use guidance: for browser login and token retrieval, with two clear alternatives—permanent via config header or session-only via token parameter. It also instructs when to call with no args to get the link, effectively mapping usage scenarios to invocation patterns.

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, so the safety profile is covered. The description adds behavioral context about the two possible return states (authenticated:true with empty pending[] vs. connect_url). This is useful but not extensive. It doesn't mention any side effects or additional behavior, but given the annotations, a 3 is appropriate.

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 main purpose, and provides concrete details about the return values. Every sentence earns its place. No 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's simplicity (no params, no output schema), the description is complete enough. It explains the two possible outcomes and what URLs are returned. It could mention that it's a read-only status check, but annotations already cover that. The description is sufficient for an agent to know what to expect.

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

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

The tool has zero parameters, and schema coverage is 100% (vacuously). The description doesn't need to explain parameters. The baseline for 0 params is 4, and the description adds value by explaining the output states, which is more than necessary. No deduction needed.

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, and distinguishes between two states (all connected vs. missing credentials). It is specific about the resource (connection status) and the action (returns). It doesn't explicitly name sibling tools, but the purpose is clear enough to differentiate from siblings like authenticate or toolkit_info.

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 when to use it: to check connection status and get URLs when credentials are missing. However, it doesn't explicitly state when not to use it or mention alternatives. Given the sibling tools, it could have said 'use this to check status before calling authenticate' but it doesn't. The context is clear but exclusions are absent.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true. The description greatly expands on this by disclosing that invoke runs tools one-off without installation, may require credentials or payment (returning links), that install/uninstall modify the toolkit, and that writes have permission requirements. No contradiction with annotations.

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

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

The description is a single dense paragraph with no bullet points or segmentation. While informative, it is overly verbose and hard to parse at a glance. It could be structured into sections (actions, flow, prompt library) to improve scannability. The length detracts from its utility.

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 high complexity (23 parameters, 14 actions, no output schema), the description covers most critical aspects: the core flow, auth/wallet fallbacks, permission requirements, and the distinction between ephemeral vs permanent installation. It lacks explicit return formats or error handling but is reasonably complete for the tool's scope.

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

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

Schema coverage is 0%, so the description must compensate. It explains the meaning of key parameters indirectly (e.g., action, query, mcp_id, tool_id, arguments) through the flow, and introduces concepts like connect/checkout links. However, many parameters (immediate, tier_slug, prompt_vars, conversation, cancel_reason, etc.) are not explicitly described, leaving gaps for the agent.

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

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

The description clearly states that the tool is the official marketplace for discovering, describing, and running MCPs/tools, and also covers prompt library operations. It enumerates distinct actions (search, describe, invoke, install, etc.) and explains the core flow, distinguishing it from sibling MCP-specific tools like mercos_* by explicitly positioning it as the in-platform catalog.

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

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

The description gives explicit guidance on when to use each action: 'prefer invoke for a single/occasional use', 'use install only to make an MCP PERMANENT', and explains when invoke returns connect/checkout links. It also notes permissions (writes require owner/admin) and covers the prompt library usage. This far exceeds typical usage guidance.

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

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

Annotations already mark the operation as a write, and the description adds that it adjusts stock in a batch via a specific POST endpoint. It does not clarify side effects like whether partial batches succeed, whether stock values are overwritten, or what the response contains, so the behavioral picture is incomplete.

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: one sentence covering purpose, the HTTP endpoint, and the primary parameter. There is no filler, and the most important 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?

Given that there is no output schema and annotations are minimal, the description should carry more weight. It omits the structure of a 'ajuste' object, the meaning of `account`, and any return/error behavior, making this a recognizing statement rather than a fully actionable tool definition.

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

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

The description adds semantics only for `data` ('array de ajustes'), which is valuable because the schema itself provides no descriptions. However, the `account` parameter is completely undocumented, and the schema types `data` as a string rather than an array, creating ambiguity about the actual input format. The description only partially 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 is specific: 'Ajusta o estoque de produtos em lote' clearly identifies the action (adjust), the resource (product stock), and the mode (batch). It also cites the exact POST endpoint, and it is distinguishable from sibling tools like mercos_create_produto, mercos_update_produto, and mercos_list_produtos.

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 phrase 'em lote' implies this tool is intended for bulk stock adjustments, giving some usage context. However, it does not explicitly state when to prefer this over alternatives such as mercos_update_produto, and it offers no exclusion criteria like 'use for multiple products only'.

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 this is a write operation (readOnlyHint=false) and non-idempotent. The description adds value by noting that `data` can be an object or array, enabling batch creation, but does not disclose response behavior, authentication prerequisites, or side effects beyond the endpoint.

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, direct sentence that includes the endpoint and the key parameter clarification. No filler or redundancy; it is appropriately sized for a simple create endpoint.

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 creation tool with no output schema, the description covers the core action and the data parameter's batch capability. However, it omits expected return values, the meaning of `account`, and any error or validation behavior, leaving noticeable gaps for an agent to invoke correctly in all contexts.

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 clarifies that `data` can be an object or array of clients, which is helpful, but the `account` parameter is left unexplained, and the internal structure of a 'cliente' is not detailed.

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 'Inclui cliente(s) (POST /v1/clientes)' clearly identifies the creation of clients and the target resource/endpoint. It is distinct from siblings like mercos_update_cliente and mercos_list_clientes, though the verb 'Inclui' is slightly less explicit than 'creates.'

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 a create operation via the verb 'Inclui' and the POST endpoint, but provides no explicit guidance on when to use this tool versus alternatives like update or list. The distinction is largely inferred from the tool name and sibling list rather than stated.

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 it is not read-only (readOnlyHint=false) and not idempotent/idempotentHint=false). The description adds the HTTP method and endpoint, and the main content of `data`, but does not disclose side effects, auth requirements, or rate limits. Since annotations cover the basic mutation profile, this is adequate but not enriched.

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 front-loads the primary action, endpoint, and main parameter content. It is concise and to the point with no redundancy.

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

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

Given there is no output schema, the description should explain the return value or consequences of the operation. It also leaves the full structure of `data` and the purpose of `account` unexplained. For a create tool with a complex payload, this is insufficient for an agent to confidently use it.

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

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

With 0% schema description coverage, the description must compensate. It partially explains the `data` parameter (client, items, payment condition) but does not clarify its format (likely a JSON string) or the `account` parameter at all. The description fails to give meaningful semantics beyond what the parameter names imply.

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

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

The description explicitly states it creates an order via POST /v2/pedidos, with `data` containing client, items, and payment conditions. This clearly distinguishes it from sibling tools like mercos_update_pedido or mercos_list_pedidos. However, it lacks the specificity of naming the exact resource or operation beyond 'includes an order', which is slightly vague.

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?

There is no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or alternative tools for related operations. The usage is only implied by the name and endpoint.

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 all false, so the description carries some burden. It adds the HTTP method and clarifies that 'data' can be an object or array, which goes beyond the schema's string type. However, it does not mention side effects, permissions, or error behavior, making it minimally transparent.

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, focused sentence with no wasted words. It conveys the core action and the data format efficiently.

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 creation tool with no output schema and limited annotations, the description is insufficient. It does not mention the 'account' parameter, expected response, required product fields, or error handling. The tool feels underspecified for practical 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?

Schema coverage is 0%, so the description must explain parameters. It partially compensates by explaining 'data' (object or array of products) but ignores 'account' entirely. The mismatch between the schema's string type and the description's object/array is not reconciled, leaving room for confusion.

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 includes/adds product(s) via POST to /v1/produtos, which distinguishes it from update and list siblings. It uses a specific verb and resource, though 'inclui' could be more explicit about creating new products.

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

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

No guidance is provided on when to use this tool versus alternatives like mercos_update_produto or mercos_list_produtos. It lacks any contextual cues, prerequisites, or 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?

The description discloses a POST request, implying a mutating create operation, consistent with readOnlyHint: false. However, it does not explain side effects, required authentication, idempotency, or any rate limits. The mention of 'data' containing fields is minimal and does not elaborate on behavior in edge cases.

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, succinct sentence with no unnecessary words. It efficiently conveys the core function and includes an example-like reference to the endpoint. There is no redundancy or bloat.

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 create operation with no annotations or output schema, the description is insufficient. It omits details such as expected response, error behavior, required fields within 'data', and the purpose of 'account'. The tool remains under-specified for an agent to use correctly without additional 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?

With 0% schema coverage, the description carries the burden. It adds context for the 'data' parameter ('com os campos da tabela') but not for 'account'. The format and required structure of 'data' remain unclear, offering only marginal value beyond the schema itself.

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 indicates a price table creation operation via 'Inclui uma tabela de preço' and explicitly includes the endpoint 'POST /v1/tabelas_preco', distinguishing it from sibling tools like 'mercos_list_tabelas_preco' for listing. While the verb 'Inclui' could be more specific (e.g., 'create'), the name and HTTP method remove 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 provides no guidance on when to use this tool versus alternatives. It does not mention related tools like mercos_list_tabelas_preco or any scenarios where creating a price table is appropriate, leaving the agent without context for 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?

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds that it lists companies 'connected to this install', providing context about scope. It does not add more behavioral details beyond annotations but is not contradictory.

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 with no redundant or unnecessary details. It is well-structured and easy to understand.

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 gives a basic idea of the output (id and label) but omits important context about the 'account' parameter, which could be a filter. Since there is no output schema, the description should clarify return structure more fully, but it states the tool lists accounts, which is a reasonable baseline.

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

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

The only parameter 'account' is not described at all. The description does not explain its purpose, whether optional, or how it affects the listing. With 0% parameter coverage, the description fails to compensate.

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 Mercos companies connected to the install, with id and label. It uses a specific verb (list) and resource (companies/accounts), and is distinct from sibling tools that handle other entities.

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 state when to use this tool over alternatives, nor does it mention exclusions or alternatives. Usage is implied as 'when you need to list accounts', but no explicit 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the GET endpoint, which reinforces the read-only nature, but it does not disclose pagination, filtering behavior, or authentication needs.

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 with no filler. It conveys the core purpose and endpoint efficiently, earning its place without unnecessary detail.

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 simple annotations, the tool has three undocumented optional parameters and no output schema. The description is too thin to fully equip an agent: it omits parameter meaning, return behavior, and any filtering details, so it is not complete enough for reliable 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%, and the description does not explain any of the three parameters (account, filters, alterado_apos). Since the schema provides no descriptions and the tool description does not compensate, parameter semantics are entirely absent.

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 ('Lista') and resource ('categorias de produtos') and includes the exact endpoint (GET /v1/categorias). This clearly distinguishes it from sibling list tools like mercos_list_produtos and mercos_list_clientes.

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

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

No guidance is provided about when to use this tool versus alternatives, nor any exclusions or prerequisites. The description only states what the tool does, leaving the agent to infer usage context from the name and endpoint.

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 established. The description adds the incremental-filter behavior and confirms the GET endpoint, but does not disclose pagination, response format, or auth needs. This is adequate given the annotations, but not rich.

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 short sentences, front-loaded with the primary purpose and containing no filler. Every word earns its place, and the incremental tip is efficiently appended.

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 is a simple list operation with three optional parameters and no output schema. The core purpose is clear, but the lack of detail on `account` and `filters` creates gaps in contextual completeness. For a low-complexity read-only tool, this is a minimally viable description, but it could easily include parameter semantics.

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

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

Schema description coverage is 0%, and the description only explains `alterado_apos` (for incremental). The other two parameters, `account` and `filters`, are left entirely undocumented, leaving the agent guessing about their format and purpose. The description does not compensate 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 begins with 'Lista clientes' (lists clients), a specific verb+resource pairing that clearly states the tool's function. The endpoint reference '(GET /v1/clientes)' further clarifies the operation, and the resource distinguishes it from sibling list tools like mercos_list_pedidos or mercos_list_produtos.

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 phrase 'Use `alterado_apos` pra incremental' provides a concrete usage guideline for a specific scenario (incremental sync). However, it does not explicitly mention alternatives for creating or updating clients, nor when not to use this tool, so it falls short of the top score.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this with the GET method and adds the filter behavior, but it does not disclose pagination, return format, or authentication needs. No contradiction with annotations.

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

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

The description is a single compact sentence that front-loads the core action, includes the endpoint, and states the key filtering option. There is no filler or redundant 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 read-only list tool with no output schema, the core operation and primary filter are present. Yet the undefined `account` and `alterado_apos` parameters, plus no mention of pagination or response behavior, leave some gaps for an agent invoking the tool.

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

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

With schema description coverage at 0%, the description adds meaning to `filters` by explaining it accepts colaborador_id or pedido_id. However, `account` and `alterado_apos` remain undocumented, so the description only partially compensates for the missing 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 opens with the specific verb 'Lista' and the resource 'comissões', and adds the REST path GET /v1/comissoes. This clearly states what the tool does and distinguishes it from sibling list tools for other Mercos entities.

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: use this tool to list commissions, with filtering guidance via `filters`. It does not explicitly name alternatives or exclusions, but no sibling tool covers commissions, so the usage context is unambiguous enough.

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 indicate read-only, idempotent, and non-destructive behavior, which covers the main safety traits. The description adds no further behavioral details (e.g., pagination, auth), so it meets the baseline but does not exceed it.

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 includes the HTTP endpoint, making it both brief and informative. No unnecessary details or verbosity are present.

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 list operation, the description provides enough context to understand the basic function. However, it omits details about return format, pagination, or parameter usage, leaving some gaps 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 includes three parameters (account, filters, alterado_apos) with no descriptions, and the tool description does not explain them. The parameter names give partial hints, but without explicit explanation, the description fails to compensate for the lack of schema documentation.

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

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

The description clearly states the tool lists payment conditions and provides the endpoint, making its purpose unambiguous. It also naturally distinguishes itself from sibling list_* tools by specifying the resource type.

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 payment conditions but does not explicitly state when to use it versus alternatives. It lacks guidance on filtering or context where other tools might be preferred, so the usage 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, which covers the safety profile. The description adds the endpoint and a note that orders live in v2, but it does not disclose pagination behavior, return format, or rate limits, so it contributes only moderate 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 extremely concise: one short sentence plus a parenthetical, with no filler or repetition. It front-loads the core purpose and immediately follows with a practical usage hint.

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 read-only list tool with good annotations and no output schema, the description is minimally adequate but leaves gaps: no mention of return values, pagination, or the meaning of 'account' and 'filters'. It provides enough for basic invocation but not full self-sufficiency.

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 only explains 'alterado_apos' (for incremental updates) but leaves 'account' and 'filters' entirely undocumented, which is insufficient for a tool with no schema-level documentation.

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

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

The description clearly states 'Lista pedidos' (lists orders), specifies the exact endpoint GET /v2/pedidos, and is distinct from sibling tools like mercos_create_pedido and mercos_update_pedido. The verb+resource combination is specific and immediately identifies the tool's function.

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 gives clear, actionable usage guidance: 'Use alterado_apos pra incremental' tells the agent how to perform incremental listing. It does not explicitly discuss exclusions or named alternatives, but the context of listing orders is clear enough for ordinary use.

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

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

Annotations already declare readOnlyHint: true, destructiveHint: false, and idempotentHint: true, so the safety profile is covered. The description adds the incremental fetch tip and the HTTP method, but does not disclose additional behaviors like pagination or response format. With annotations present, the bar is lower, and the description provides 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 extremely concise—two short sentences that immediately state the purpose and a key usage tip. There is no fluff or repetition, making it front-loaded and efficient.

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

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

For a simple list tool with good annotations and no output schema, the description is mostly sufficient. However, it leaves two parameters unexplained and does not mention any filtering or account considerations. The tool is simple enough that it might work, but adding parameter context would improve completeness.

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

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

The schema has 0% description coverage and three parameters, but the description only explains 'alterado_apos' for incremental fetching. Parameters 'account' and 'filters' are not explained at all. Since the description fails to compensate for the lack of schema documentation for most parameters, it misses the opportunity to add necessary meaning.

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

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

The description states 'Lista produtos cadastrados' (lists registered products) and includes the HTTP endpoint 'GET /v1/produtos'. This clearly identifies the tool's purpose and action, easily distinguishing it from sibling tools like mercos_create_produto or mercos_list_pedidos.

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 using 'alterado_apos' for incremental fetching, which is a useful hint. However, it does not clarify when to use this tool versus other list tools or provide exclusions or alternative selections. The guidance is minimal and only hints at one parameter usage.

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=true, idempotentHint=true, and destructiveHint=false, so the tool is clearly safe. However, the description adds nothing beyond the endpoint, such as pagination behavior, result scope, or authentication specifics. With annotations covering safety, the description still should provide some behavioral context, but it does not.

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 one sentence and front-loaded with the tool's purpose and endpoint. There is zero fluff, and every word serves a functional purpose. It is concise to a fault but earns full marks for structure and brevity.

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 3 unannotated parametersappers, no output schema, and no parameter descriptions, the description fails to provide necessary context. It does not explain pagination, filtering syntax, required authentication, or return behavior. The endpoint path is a hint, but not enough for an agent to use the tool confidently.

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

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

Schema description coverage is 0% and there are 3 parameters (account, filters, alterado_apos) that are completely undocumented in the description. The description provides no meaning beyond the parameter names, which are ambiguous (e.g., 'filters' as a plain string). This is a severe 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 states the tool lists price tables and gives the endpoint, which is a clear verb+resource pattern. However, it does not distinguish this from sibling list tools like mercos_list_clientes or mercos_list_produtos, and the phrase 'tabelas de preco' is not elaborated to clarify its business meaning.

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?

There is no guidance on when to use this tool versus other listing tools, nor any context about typical use cases. The description simply names the operation and endpoint, so an agent gets no help in deciding between this and similar list tools.

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

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

Annotations already declare readOnlyHint:true, idempotentHint:true, destructiveHint:false. Description adds nothing beyond 'list', but it is consistent with annotations. No extra behavioral details such as limits, auth, or return specifics.

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 short sentence, extremely concise with no fluff. It is front-loaded with the core action and resource, but its brevity borders on under-specification, hence not a 5.

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 three undocumented parameters MATERIAL-ONLY and no output schema, the description provides no contextual guidance on filters, authentication, or expected results. It is minimally adequate for a simple list operation but leaves significant gaps.

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

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

Schema description coverage is 0% and the description mentions none of the three parameters (account, filters, alterado_apos). It provides zero semantic value beyond parameter names. With no parameter info in either schema or description, the agent is left guessing.

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 'Lista títulos financeiros' clearly identifies the verb (list) and resource (financial titles). It also includes the endpoint GET /v1/titulos, which is specific. It distinguishes itself from sibling list tools by naming the specific resource.

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

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

No guidance on when to use this tool over alternatives like mercos_list_pedidos or mercos_list_comissoes. No explicit context or exclusions 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the description carries little additional behavioral burden. However, it adds only the HTTP endpoint (GET) and nothing about pagination, filtering semantics, or response characteristics—limited value 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 extremely concise and front-loaded, but it is under-specified. It avoids fluff yet fails to include essential parameter or behavior information, making it minimally sized but not appropriately sized for a tool with three undocumented parameters.

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

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

For a simple read-only list operation, the description plus annotations cover the safety profile, but the tool is not fully understandable: parameter semantics are absent, no output format is described, and no filter or account context is given. The agent would struggle to invoke this tool correctly in a non-trivial way.

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% with three parameters (account, filters, alterado_apos) and no descriptions. The tool description does not compensate by explaining any parameter meaning, leaving the agent with no information about what these fields do or expect.

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 a specific verb ('Lista') and resource ('transportadoras'), clearly indicating the tool lists carriers. The HTTP endpoint further clarifies the scope and distinguishes it from other mercos_list_* siblings.

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

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

No guidance is given on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description only states what it does, leaving the agent to infer usage solely from the resource type.

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 behavior. The description adds the endpoint but does not mention any side effects or additional behavioral details. Since it's a read operation, the transparency is sufficient, but the description itself adds little 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 concise sentence that directly conveys the tool's purpose and endpoint. It avoids unnecessary detail and is well-structured for a short tool 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?

While the tool is simple (no output schema), the lack of any parameter explanation makes it incomplete. Users cannot effectively use the tool without understanding what account, filters, and alterado_apos represent. The description does not compensate for the missing parameter documentation.

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

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

The three parameters (account, filters, alterado_apos) have no descriptions in the schema, and the tool description does not explain their meanings or usage. There is zero parameter documentation, making it impossible for a user to know how to set these fields correctly.

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 sellers/users, which is a specific resource. The endpoint /v1/usuarios is provided, and among sibling list tools it's distinct in scope. The purpose is 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?

The description gives the HTTP method and resource but does not explicitly state when to use this tool versus other list tools (e.g., mercos_list_clientes). It implies usage for user/seller listings, but lacks explicit context or exclusions. Adequate but minimal.

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

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

Annotations only provide generic flags (readOnlyHint=false, destructiveHint=false), so the description carries the burden of behavioral disclosure. It usefully reveals the PUT method and bulk execution via ids, but it does not explain batch semantics, atomicity, failure behavior, or whether `data` must be a JSON string. No contradiction with annotations was found.

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 short, front-loaded sentences with no filler. The first sentence states the operation and endpoint, and the second adds bulk behavior, earning every word.

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 minimal annotations, the description provides the core operation and bulk capability but omits return-value expectations, data encoding details, and account semantics. It is adequate for a simple update tool but leaves operational uncertainty for an agent.

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 clarifies that `id` identifies the client and `data` contains the fields to change, and it mentions `ids` for bulk. However, it does not explain the format of `data`, how `id` and `ids` interact, or what the `account` parameter means, leaving significant gaps.

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

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

The description opens with 'Altera um cliente' and explicitly states the HTTP method and endpoint (PUT /v1/clientes/{id}), making the action and target resource unambiguous. This clearly distinguishes it from sibling create/list 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 verb 'Altera' implies this tool is for modifying an existing customer, and the bulk-support note adds usage context. However, it does not explicitly state when to use this tool versus mercos_create_cliente or mercos_list_clientes, nor does it mention exclusions 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 provide no safety hints (all false), so the description carries the burden. It mentions 'Altera' and PUT, but does not disclose partial vs full replacement, side effects, required permissions, or error behavior. The bulk support is extra, but the overall transparency is minimal.

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

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

Two short sentences, front-loaded with the core purpose and a concise note on bulk support. Zero fluff; every word earns its place.

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

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

With no annotations, no output schema, and 4 parameters, a richer description is needed. It lacks details on preconditions, semantics of partial updates, how account is used, and success/failure responses. The description is too sparse for a mutating 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%, and the description explains id and data as responsible for the fields to change, and ids for bulk execution. However, account is unexplained, and the format of 'data' (likely JSON) is not stated. It adds meaningful context for 3 of 4 parameters but not enough depth.

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 alters an order via PUT /v2/pedidos/{id}, and mentions bulk support, which distinguishes it from create_pedido and list_pedidos siblings. The verb 'Altera' (change) with the resource 'pedido' is specific and unambiguous.

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

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

The purpose implies when to use it (modifying existing orders), but it does not explicitly exclude creating new orders (which would use create_pedido) or listing them. The guidance is implicit rather than explicit, leaving some room for ambiguity 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?

The annotations provide no behavioral information (all hints false). The description discloses that it's an update (PUT) but lacks details on side effects, idempotency, error handling, or permissions. This leaves significant gaps in understanding the tool's runtime behavior.

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 short sentences. It presents the core functionality and bulk support without extraneous information, making it easy to parse.

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 essential operational aspects (endpoint, parameters, bulk support) but does not address error conditions, data format expectations, or authentication requirements. Given no output schema, return value details are not mandated, but additional context would improve completeness.

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

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

The description clarifies the purpose of `id` (product identifier) and `data` (fields to alter), and mentions `ids` for bulk operations. However, `account` is not explained, and the schema provides no descriptions. Coverage is approximately 75%, so the description adds some value but is incomplete.

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: 'Altera um produto' (alters a product) with the HTTP method PUT and endpoint. It distinguishes from sibling tools like mercos_update_cliente and mercos_update_pedido by specifying the resource type.

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 by specifying the HTTP method, endpoint, and required parameters (`id` + `data`). It also mentions bulk support via `ids`, which provides practical usage guidance. However, it does not explicitly state when to use this tool over others or exclude 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?

The description does not disclose any behavioral side effects beyond what annotations already state. It doesn't mention whether data is transmitted, stored, or how it is processed, leaving the user unaware of the tool's impact.

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, using a single sentence to convey the key action and a specific instruction. There is no redundancy or unnecessary wording.

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

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

The description lacks sufficient context about how to use the tool effectively. It does not explain what constitutes a valid bug report, how to format the conversation array, or what the 'context' field is for, making the tool under-specified.

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 mentions the 'conversation array' but does not clarify the meaning or required format of 'context' or 'message'. Since the schema provides no descriptions, this leaves two parameters completely unexplained.

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 bugs, missing features, or sending feedback. It is specific and unambiguous, leaving no doubt about what the tool does.

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 other tools or when not to use it. It lacks contextual triggers or alternative recommendations, providing only a generic 'report' instruction.

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 description adds value by specifying that it returns both platform and adapter versions. However, it does not disclose any additional behavioral traits like output format or whether it makes network calls. With annotations covering the safety profile, a 3 is appropriate.

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 with no extraneous words. It fully communicates the tool's purpose in the most efficient manner possible.

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 version tool with no parameters and no output schema, the description is complete. It explicitly identifies what information is returned (platform and adapter versions), leaving no ambiguity about the tool's behavior.

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% (empty schema). The baseline for 0 params is 4, and the description adds some context by mentioning the exact version categories (platform and adapter), which slightly enriches the parameter-less invocation.

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 ('Show') and the resource ('current MCP platform and adapter versions'). It is specific and distinguishes the tool from the business-oriented sibling tools, which all deal with Mercos data or authentication.

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

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

No usage guidance is provided. The description does not mention when to use this tool versus alternatives, nor any context such as checking compatibility or troubleshooting. While the use case is intuitive for a version tool, the lack of explicit guidance keeps it at a low score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the safe, non-mutating nature. The description adds value by specifying exactly what aspects of state are returned (installed MCPs, connection status, accounts, catalog tool counts), which complements rather than contradicts 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?

A single, well-formed sentence that front-loads the action ('Returns the current toolkit state') and then lists the informational components in a clear, comma-separated sequence. There is absolutely no waste 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 zero-parameter, read-only tool with rich annotations, the description fully covers what the agent needs to know to invoke and interpret the result: it enumerates the exact contents of the toolkit state. No output schema exists, but the description compensates by listing the returned information areas.

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 100% (empty schema), so there is nothing for the description to disambiguate. The baseline of 4 for no parameters applies; the description correctly avoids inventing parameter details.

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 'Returns' and clearly identifies the resource as the current toolkit state, enumerating concrete contents: installed MCPs, connection status, accounts, and catalog tool counts. This distinguishes it well from sibling tools like connect, authenticate, or 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?

No explicit when-to-use guidance or alternatives are provided. However, the description's enumeration of state information implies it is suitable for inspection/monitoring tasks, and the read-only nature is clear. There is no direct comparison to sibling tools, so usage context is only implicit.

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