Correios: Entrega Diferenciada

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

Annotations already indicate idempotent and non-destructive. The description adds valuable context beyond annotations: the two authentication modes (permanent vs session), the workflow (log in browser, copy token), and that calling with no args returns a link. This is useful and doesn't contradict annotations.

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

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

The description is information-dense yet concise, front-loading the core purpose and then detailing two usage paths. Every sentence adds value—no redundancy or filler.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all necessary aspects: purpose, login flow, token usage, and alternative methods. It is complete for an agent to select and invoke correctly.

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

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

The only parameter 'token' is explained in the description: 'call with { token: "<jwt>" }' and its optionality ('no args to get the link'). Given 0% schema description coverage, the description fully compensates by clarifying the token's format and purpose.

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: to authenticate the user for MCP.AI in IDE agents. It specifies the action (log in, get token) and distinguishes from siblings by focusing solely on authentication, with explicit alternate methods (config vs session).

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 usage guidance: recommends adding a permanent header to config, or passing a token for session-only login, or calling with no args to get the link. Clearly explains when to use each approach, fulfilling the when/alternatives criterion.

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 meaningful behavioral context by explaining the two possible response states: authenticated:true with empty pending[] versus connect_url and per-install URLs when credentials are missing. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences with no filler. The first sentence front-loads the core purpose ('Returns connection status and URLs'), and the second sentence efficiently explains conditional response behavior. 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?

Given the tool's low complexity, zero parameters, and rich annotations, the description is largely complete. It explains the main return variants (authenticated:true/pending[] vs connect_url/per-install URLs), though it does not detail the exact structure or shape of the URLs or pending array. An output schema is absent, but the description covers the meaningful return 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 schema coverage is effectively 100% by having an empty properties object. With no parameters to explain, the description does not need to add parameter-level detail. Baseline for zero-parameter tools is 4, and the description satisfies that.

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

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

The description clearly states the tool returns connection status and URLs, with a specific verb ('Returns') and resource ('connection status and URLs'). It distinguishes itself from the sibling 'authenticate' tool by focusing on status/URL retrieval rather than authentication actions, and the conditional details (authenticated:true vs connect_url) add precision.

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 contexts through conditional behavior: when all providers are connected versus when credentials are missing. However, it does not explicitly state when to use this tool versus alternatives like 'authenticate', nor does it mention exclusions or prerequisites. Usage guidance is present but implicit.

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

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

No annotation contradiction. Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context about authentication (no platform credentials), cost model (pay-per-query with prepaid credits), and legal implications (LGPD, client is data controller). This significantly enriches what annotations provide. Slight deduction because it doesn't explain return format or rate limits.

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

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

The description is dense but efficient: it's a run-on sentence but packs in purpose, authentication model, pricing, data source, and LGPD notice in under 40 words. Every clause serves a purpose. For a tool with legal and cost implications, this is appropriately concise.

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

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

The tool has a simple signature (3 flat string params), a clear domain (Correios delivery restrictions), and rich annotations that declare read-only, idempotent, non-destructive operation. The description covers the human/cost/policy context (no credentials, prepaid credits, LGPD, data controller). However, it lacks any schema for response (no output schema), so the return value remains unspecified. For a paid API with LGPD framing, the lack of any hint about response shape or error behavior is a meaningful gap, but the legal framing and cost disclosure do contextualize the operation.

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

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

Schema description coverage is 0%, so the description carries the full burden. The parameter names (servico, cep_origem, cep_destino) are self-explanatory for Portuguese speakers: service, origin CEP, destination CEP. However, the 0% coverage means no semantic detail like 'servico' options (PAC, SEDEX, etc.) or CEP format (8 digits). The description could have filled this gap but only partially compensates (it mentions dates or service types nowhere).

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 in Portuguese and mentions Correios restricted delivery consultation, but it's vague about the exact operation ('consulta em fonte oficial'). It doesn't specify what 'restrições de entrega' (delivery restrictions) means precisely or what kind of response to expect. The verb is implied rather than explicit.

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 clarifies this queries official Brazilian sources (same data available to citizens), explains it's hosted on the platform with no platform credentials, and (importantly for a Brazil-specific tool) notes LGPD compliance responsibility. It also implies when NOT to use it (not for confidential data). However, it doesn't explicitly compare to a sibling tool or list exclusion criteria.

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?

With only minimal annotations (readOnlyHint, openWorldHint), the description carries the full burden and does exceptionally well. It discloses write permission requirements (owner/admin), the one-off nature of invoke, connect/checkout link behavior, installed vs. temporary status flags, and the distinction between running and permanent installation. No contradictions with annotations.

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

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

The description is a single dense paragraph with no bullet points, headers, or separation between the MCP flow and the prompt library. It lacks front-loading and forces the agent to parse a long wall of text. While substantive, it could be significantly shortened and structured for readability.

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 high complexity (23 params, 14 actions, no output schema), the description still provides a solid high-level flow: search→describe→invoke, plus the prompt library. It explains key behaviors like ad-hoc invocation, auth/wallet links, and permission requirements. However, it omits parameter mappings and details on actions like subscribe/cancel and report_bug, so it is not fully complete.

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

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

Schema coverage is 0% for 23 parameters, and the description does not explain how 'arguments', 'tool_id', 'prompt_vars', 'conversation', etc., map to each action. It mentions the action enum and the general flow but leaves parameter usage to inference. For a tool of this complexity, the description should at least list which parameters correspond to which actions (e.g., cancel_reason for cancel, report_context for report_bug), but it does not.

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 this is the official mcp.ai marketplace and explains its two primary functions: discovering/using MCPs and managing prompts. It uses specific verbs (search, describe, invoke) and distinguishes itself from sibling tools by describing the full catalog and run flow, not just a single 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?

The description explicitly contrasts when to use invoke vs. install ('prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT') and explains when invoke returns connect/checkout links. It also mentions the prompt library as a separate category, giving clear situational guidance for each action.

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 cover idempotent and destructive hints. The description adds behavioral context by requiring the conversation array for reproduction, informing the agent what the tool needs to work effectively. It does not detail side effects, but the annotations cover safety, so the added context justifies a solid 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 two sentences long and front-loaded with the purpose. The second sentence is a precise, actionable instruction. There is no redundancy or 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?

For a simple bug-reporting tool with no output schema, the description covers the main purpose and a key input requirement. It lacks details about return values or post-report behavior, but these are not critical for a tool of this nature. The description is sufficiently complete given the tool's simplicity.

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

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

The schema has 0% description coverage, so the description must compensate for parameter meaning. It explicitly explains the 'conversation' parameter by saying to include recent messages, but it does not clarify 'message' or 'context'. This partial coverage adds some value but leaves gaps for the agent to infer.

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 with the verb 'Report' and specifies the resource types: bug, missing feature, or feedback. It also adds a specific requirement about including the conversation array, which clarifies the action further. Sibling tools are unrelated, so differentiation is not needed.

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 use cases (bug, missing feature, feedback) and instructs the agent to include the conversation array for reproduction, giving clear context on when and how to use the tool. However, it does not mention alternatives or exclusions, so it falls short of a perfect 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, covering the safety profile. The description adds minimal behavioral context beyond stating what is shown, but no extra details like caching or authentication are disclosed.

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

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

The description is a single, 10-word sentence that directly conveys the tool's purpose with no filler 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?

Given the trivial complexity (no parameters, no output schema, no nested objects), the description is fully sufficient. It tells the agent exactly what the tool returns: current platform and adapter versions.

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

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

The tool has zero parameters, so the role of the description is minimal. The baseline of 4 is appropriate since there are no parameter semantics to clarify beyond the empty schema.

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

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

The description uses a specific verb ('Show') and resource ('current MCP platform and adapter versions'), making it clear what the tool does. It is distinct from sibling tools like authenticate, connect, or toolkit_info, so there is no confusion.

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 usage is implied by the purpose: call this tool when you need version information. However, there is no explicit guidance about when not to use it or mention of alternatives, though none clearly exist among the siblings.

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

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

Annotations already declare readOnlyHint: true and destructiveHint: false. The description adds specific details about the returned state (installed MCPs, connection status, accounts, catalog tool counts), which enriches the agent's understanding beyond the annotations. It does not mention error handling or side effects, but those are less critical for a read-only state tool.

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

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

The description is a single, front-loaded sentence that begins with 'Returns the current toolkit state' and then uses a colon to introduce a concise list of state aspects. Every word adds value, and there is 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?

Despite lacking an output schema, the description enumerates the main pieces of state returned (MCPs, connection status, accounts, catalog tool counts), giving the agent a solid mental model. It could have been more explicit about data types or potential error messages, but for a stateless query, this is adequately complete.

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

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

With zero parameters, there is nothing to document. Schema coverage is trivially 100% and the rubric states 0 params gets a baseline of 4. The description adds no parameter-related info, which is appropriate here.

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

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

The description uses a specific verb ('Returns') and a specific resource ('current toolkit state'), then enumerates distinct contents (installed MCPs, connection status, accounts, catalog tool counts). It clearly differentiates from siblings like show_version by focusing on state and connected accounts.

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 clearly implies a read-only status query for inspecting current state, but it does not explicitly mention alternatives or when not to use it. It provides clear context (returns current toolkit state) but no exclusions, which fits the 'clear context, no exclusions' category.

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