Correios: CEP

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

The description discloses behavioral traits beyond annotations: the token is non-expiring when added to config, session-only when pasted, and calling with no args returns a link. It aligns with the idempotentHint annotation (calling with same token should be idempotent) and does not contradict any annotations. It adds useful context about token lifecycle.

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

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

The description is moderately concise and front-loaded with the main purpose. It is a bit dense with multiple instructions in three sentences, but each sentence adds valuable information. It could be slightly more streamlined, but it is not overly verbose.

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 the essential flows (permanent config vs session token, no-args behavior). It does not state what the tool returns after authentication, which would be helpful, but the lack of an output schema lowers the bar. Overall, it is sufficiently complete for an agent to invoke the tool correctly.

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

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

The schema has one optional parameter (token) with no description (0% coverage), so the description must compensate. It does so excellently by explaining when to include the token ('call with { token: "<jwt>" } after the user pastes') and when to omit it ('or with no args to get the link'). This gives complete semantic meaning for the parameter.

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: authenticating to MCP.AI for IDE agents by obtaining and using an access token. It mentions specific actions (log in, copy token, call with token or no args) that make it distinct from generic tools, though it does not explicitly compare against sibling tools like 'connect'.

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

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

The description provides explicit guidance on when and how to use the tool: it recommends adding the token to the server config for a permanent connection, or pasting the token for a session-only login. It also explains the no-args behavior to get the login link, giving clear context for different scenarios.

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

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

Annotations already cover read-only, idempotent, and non-destructive hints. The description adds valuable behavioral details beyond annotations, such as the authenticated field being true and pending[] being empty when all providers are connected, and the presence of connect_url in case of missing credentials. This gives a good sense of expected responses without overpromising.

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

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

Two sentences, no fluff. The first sentence states the core function, and the second explains conditional outputs. Every word adds value, and it's perfectly 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 the simplicity of the tool (no parameters, read-only, clear annotations), the description covers the primary use cases: successful connection status and missing-credential scenario. It could theoretically mention edge cases like partial connectivity, but for a status tool this is sufficient. Output schema is absent, but the description gives enough insight into the return structure.

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?

There are no parameters, and the input schema is empty. The description doesn't need to elaborate on parameters, and the baseline for zero-parameter tools is 4, which is appropriately assigned here. The schema coverage of 100% (vacuously) means nothing is unresolved.

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 'Returns connection status and URLs' with a specific verb and resource, and further elaborates on the behavior with different scenarios (all providers connected vs. missing credentials). This effectively distinguishes it from sibling tools like show_version or toolkit_info, which serve different purposes.

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

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

The description provides clear context for when to use this tool—whenever connection status or URLs are needed—and explains the conditions under which different outputs occur. However, it does not explicitly name alternative tools or state when not to use it, though the siblings list is available for contrast.

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

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

Beyond the annotations, the description discloses that it is hosted by the platform, requires no platform credentials, is pay-per-query with prepaid credit, returns non-confidential official data, and imposes LGPD responsibilities on the client. These operational and legal traits add meaningful context beyond readOnlyHint and destructiveHint.

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 front-loads the core purpose in the first phrase and then adds relevant operational, payment, and legal context in compact sentences. The paragraph is a bit dense, but each sentence earns its place, so it is appropriately concise for a commercial API tool.

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 single-parameter lookup tool, the description covers purpose, source, credentials, payment model, and data-sensitivity expectations. However, there is no output schema and no description of what the response contains or how errors/invalid CEPs are handled, leaving some practical usage 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 does not specify the expected format for the 'cep' parameter (e.g., digits only, with or without hyphen, length, or validation behavior). It merely repeats 'CEP' in the opening phrase, adding little beyond the parameter name 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 opens with 'CEP, consulta em fonte oficial,' clearly stating a specific action (querying a Brazilian postal code) and the resource (official Correios/Brazilian sources). This clearly distinguishes it from the unrelated sibling tools like authenticate, marketplace, and show_version.

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

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

The description implies usage by identifying this as a CEP lookup against official Brazilian sources and notes that the user pays per query with prepaid credit. However, it does not explicitly state when to use this over alternatives or when not to use it, and no alternative lookup tool is mentioned.

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

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

Annotations are minimal (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), so description carries the burden — and it delivers richly. It discloses that invoke runs tools one-off without installing/bloating the toolkit, returns connect links for auth and checkout links for insufficient wallet (with retry protocol), flags installed_in_toolkit vs workspace in search results, and states write operations require owner/admin. No contradiction with annotations; adds substantial behavioral context far beyond what annotations declare.

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 wall of text — no bullets, sections, or topic headers — making it hard to scan. It is information-dense and every sentence earns its place, but for a tool with 14 actions and 23 parameters the lack of structural breakdown hurts digestibility. Front-loaded with the marketplace identity but the invoke edge-cases and prompt library content arrive as a continuous stream rather than organized segments.

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 highly complex tool (23 params, 14 actions, no output schema, sparse annotations), the description thoroughly covers the core workflow, invoke edge cases, install vs ephemeral semantics, permissions, and the prompt library subsystem. However, completeness is undermined by the 0% parameter coverage — any agent needing to set prompt_vars, cancel_reason, tier_slug, or arguments must guess formats. The behavioral side is strong, but the parameter side leaves major 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% across 23 parameters. The description explains the action enum values in workflow context but leaves most parameters undefined: limit, mcp_id, tool_id, arguments, immediate, tier_slug, cancel_reason/cancel_comment, conversation, prompt_* fields, report_context, request_name, request_details, and prompt_targets are all undocumented. Even the cancel_reason enum values (only 2 enums exist) are not elaborated. With near-zero schema coverage, the description fails to compensate for the majority of parameters agents must fill.

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

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

Clearly identifies as the mcp.ai marketplace catalog and execution platform. Distinguishes from siblings (authenticate, connect, correios_cep_consultar) by naming its catalog/run role, and lays out the core search→describe→invoke flow explicitly. The description names specific capability request examples ('find an MCP that does X', 'consulta um CPF') making purpose unmistakable.

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

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

Exceptional guidance with explicit when-to-use vs alternatives: 'Use install only to make an MCP PERMANENT in the active toolkit... prefer invoke for a single/occasional use.' Also directs request_mcp for building NEW MCPs when nothing fits, distinguishes search_prompts vs search, and covers permission requirements for writes (owner/admin). The invoke path with connect/checkout links plus retry instruction is concretely actionable.

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

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

Annotations already declare the tool as non-read-only, idempotent, and non-destructive. The description adds context about including a conversation array but does not disclose additional behavioral traits such as side effects or authentication requirements. This matches the 'adds some value but not rich behavioral context' level.

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 that front-loads the purpose and then adds a concise usage tip. Every word earns its place, and it is immediately scannable.

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 low-complexity tool with simple string parameters and strong annotations, the description suffices. It explains the main action and gives a key reproduction hint. However, it could briefly note that 'message' is required or what happens after submitting, making it nearly complete but not perfect.

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

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

Schema coverage is 0%, so the description must compensate. It explicitly instructs to include the 'conversation array,' which helps for that parameter, but it says nothing about the required 'message' or optional 'context' fields. The description provides minimal added meaning beyond the parameter names themselves.

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: 'Report a bug, missing feature, or send feedback.' This is a specific verb+resource that distinguishes it from sibling tools like connect or show_version. It leaves no ambiguity about what the tool accomplishes.

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 instruction 'Include the conversation array with recent messages for reproduction' provides explicit usage context for a key parameter, but it does not contrast with alternatives or state when not to use it. The purpose is clear enough that an agent would know when to invoke it, but it lacks explicit exclusions or alternative references.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds specificity about what is shown ('MCP platform and adapter versions') and clarifies it is a current-state read operation, consistent with the annotations. No contradiction or hidden 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 a single, front-loaded sentence with no filler or redundant qualifiers. Every word contributes meaning, making it maximally concise and 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?

For a zero-parameter, read-only version-reporting tool with strong annotations and an empty schema, the description fully covers what the tool does. No additional return-value detail is necessary given the absence of a defined output schema and the trivial complexity.

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

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

The input schema has zero parameters, and the baseline for zero-parameter tools is 4. The description adds no parameter semantics because there are none to explain, which is appropriate and requires no compensation.

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 names the resource ('current MCP platform and adapter versions'), making the tool's function immediately clear. It distinguishes itself from sibling 'toolkit_info' by explicitly scoping to version information.

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

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

The description implies the usage context (when you need to know platform/adapter versions) but does not explicitly state when to prefer this tool over alternatives like 'toolkit_info' or provide any exclusion guidance. This is adequate for a self-explanatory version check but lacks explicit direction.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds valuable context about the scope of the returned data (connection status, accounts, tool counts), which goes beyond the annotations. It doesn't mention latency or error behavior, but for a read-only state tool, this is adequate.

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 is front-loaded with the core action ('Returns the current toolkit state') and then lists the key details in a compressed enumeration. Every word adds value; no filler or repetition.

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

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

For a tool with zero parameters and no output schema, the description fully covers what the tool does and what it returns. It's a simple read-only status tool, and the description provides sufficient context for an agent to understand when to invoke it. The only missing element is explicit guidance on when to use it, but that's covered by the usage guidelines dimension.

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 and 100% schema coverage (empty schema), the baseline is 4. The description implicitly explains that no parameters are needed since it returns the whole state, which is redundant but harmless. It adds no param details because none exist, and the schema already documents that clearly.

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

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

The description uses a specific verb 'Returns' and clearly defines the resource as 'current toolkit state', then enumerates exactly what is included (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from sibling tools like authenticate and connect, which perform actions rather than report status.

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

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

The description implies an informational use case but does not explicitly state when to use it over alternatives. There is no mention of 'use this to check status before connecting' or any exclusions. It provides clear context but lacks explicit when/when-not guidance, so it earns a mid-range score.

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