Light: Download via CEP + OCR

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

Beyond the annotations, the description discloses that no-arg calls return a login link, token calls create a session-only login, and the header approach provides a permanent non-expiring connection. These behavioral details align with idempotentHint=true and readOnlyHint=false, with no contradictions.

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

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

The description is compact and front-loaded with the tool's purpose, using 'Best:' and 'Or:' to structure two distinct auth paths. Both sentences earn their place, though the second sentence is somewhat dense in its juxtaposition of config and session-only options.

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

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

For a simple one-optional-param authentication tool with no output schema, the description covers purpose, token semantics, no-arg behavior, and permanent vs session-only options. It omits response/error details, but those are not critical given the tool's low complexity and adequate annotations.

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 only lists an optional string 'token' with no description, so the description carries the full burden. It explains that token is a JWT, shows the call shape { token: "<jwt>" }, and clarifies that omitting it returns the login link. This fully compensates for the 0% schema description 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 clearly states the action: logging in to MCP.AI for IDE agents and obtaining/copying an access token. It is specific about the resource and context (Cursor, etc.), and while it does not explicitly compare itself to sibling tools like 'connect', it is distinguishable as the authentication flow.

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 concrete usage paths: use the config header for a permanent non-expiring connection, or pass a token for a session-only login, or call with no args to get the link. It lacks an explicit 'when not to use' or direct contrast with alternative tools, but the guidance is actionable and context-rich.

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 readOnly=true and idempotent=true, and the description doesn't contradict them. It adds valuable context by describing the state-dependent response (e.g., authenticated:true with empty pending[] vs. connect_url), which goes beyond the annotations' boolean flags.

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 to three tight sentences with a front-loaded main verb and purposeful conditional logic. Every sentence serves a clear informational purpose with 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?

For a simple read-only status tool with no parameters and strong annotations, the description covers the key states effectively. Additional details like error handling would be nice but aren't critical for a tool of this complexity.

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

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

With zero parameters and 100% schema coverage, the description isn't expected to explain parameters. Baseline of 4 is appropriate for a parameter-less tool.

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

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

The description uses a specific verb+resource: 'Returns connection status and URLs' and details conditional outputs. It implicitly distinguishes itself from siblings like 'authenticate' by framing itself as a status retrieval, though it doesn't explicitly name them.

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 or when-not-to-use guidance is offered. While the conditional output behavior is described, there's no direction on when to call this tool instead of authenticating or other 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 idempotentHint=true; the description adds meaningful behavioral context beyond that: payment model, hosting, public official-source nature, LGPD data-controller responsibility, and reassurance that data is not confidential. It does not contradict the annotations and provides useful operational expectations.

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 compact and front-loaded with the core function in the first clause. It then adds necessary context about credentials, pricing, data source, and legal responsibility. A slight redundancy exists between 'fonte oficial' and 'fontes e órgãos oficiais brasileiros', but overall the structure is 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?

With no output schema and no parameter descriptions, the description carries the burden of explaining inputs and outputs. It provides high-level context (official data, prepaid billing, LGPD) but omits the meaning of three parameters, the OCR workflow, return format, and failure/edge-case behavior. The tool is therefore not fully actionable from the description alone.

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 needed to explain all parameters. It only hints at 'CEP' and 'OCR', leaving cpf, cnpj, and instalacao entirely unexplained. This is insufficient for a 4-parameter tool where only cep is required and the roles of the remaining parameters are non-obvious.

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

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

Description states a specific action ('Download via CEP + OCR, consulta em fonte oficial') and identifies Brazilian official sources, but it does not clearly specify what resource is being retrieved (e.g., utility bills from Light) or what output the caller should expect. The tool name suggests 'contas_light', but the description never explicitly confirms this, making the purpose only moderately clear.

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

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

The description gives useful operational context: no platform credentials required, prepaid credit is charged per query, and the data is public/non-confidential. However, it does not state when to choose this tool over alternatives, nor does it mention any exclusions or conditions that would guide tool selection 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?

Reveals key behaviors not implied by annotations: invoke runs a tool even when not installed (one-off, without bloating the toolkit), may return connect/checkout links requiring user action, and writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin. This adds valuable operational detail beyond the openWorldHint/idempotentHint 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 single paragraph is dense but every sentence contributes substantive information, from the opening purpose statement through flow, behavioral edge cases, and permission requirements. It is not verbose or repetitive, though it could be more scannable with bullets.

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 23 parameters and no output schema, the description covers the main workflow and several edge cases, but leaves many parameter details and return-value formats unaddressed. The high-level picture is complete, but the full surface area is not; an agent would still need to infer semantics for many optional parameters.

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 provides semantic meaning for the action enum and references tool_id/mcp_id in the workflow, but does not explain the other 20+ parameters (limit, query, immediate, tier_slug, prompt_vars, cancel_reason, etc.). With schema description coverage at 0%, the description only partially compensates for the missing parameter documentation.

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

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

Description immediately states the tool's identity and function: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It clearly enumerates the main actions (search, describe, invoke) and the prompt library, distinguishing it as the central discovery/execution hub versus sibling 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?

Gives explicit usage directives: 'Use install only to make an MCP PERMANENT' and 'prefer invoke for a single/occasional use.' It also outlines the core flow (search → describe → invoke) and explains when to use request_mcp, subscribe/cancel, and the prompt actions. This goes beyond vague context to active decision 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 provide idempotentHint=true and destructiveHint=false, lowering the burden on the description. The description adds the useful behavioral detail that recent messages should be included for reproduction, but it does not describe side effects, authentication needs, or response behavior beyond what annotations already signal.

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

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

The description is a single, front-loaded sentence that states purpose and the key usage detail with no redundant or filler 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?

For a simple 3-parameter reporting tool with no output schema, the description covers the main purpose and the critical reproduction detail. Minor gaps include the unexplained 'context' parameter and no mention of what happens after submitting, but these do not seriously block correct usage.

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 is responsible for explaining parameters. It adds meaning for conversation ('recent messages for reproduction') but leaves the required 'message' parameter and the optional 'context' parameter undefined, forcing the agent to infer their 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 uses a specific verb ('Report') with clear resources ('bug, missing feature, or feedback'), which expands beyond the tool name and defines purpose precisely. It also distinguishes the tool from unrelated siblings like authenticate, connect, and marketplace.

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

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

The description makes the primary use case clear: file bugs, missing features, or feedback, and includes the practical instruction to add the conversation array for reproduction. It does not explicitly compare to alternatives, but no sibling tool covers reporting, so the context is clear and no exclusions are needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the behavioral detail that it reports the 'current' versions, implying a live retrieval at invocation time, which goes slightly 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, front-loaded sentence with no filler or repetition. Every word adds meaning, and it is appropriately minimal for such a simple 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 zero-parameter, read-only, idempotent version-reporting tool, the description is fully adequate. It states exactly what information is returned (platform and adapter versions) and does not require an output schema explanation for such a trivial response.

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 its input schema is empty, so parameter documentation is not needed. The baseline for zero-parameter tools is 4, and the description sufficiently describes what the tool reports without needing to explain any parameters.

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 precise resources ('current MCP platform and adapter versions'). It immediately distinguishes this tool as a version-information read operation, especially relative to sibling tools like authenticate or 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 implies it should be used when you need to know the platform/adapter versions, but it does not explicitly state when to choose this over alternatives like toolkit_info. There are no exclusions or context cues beyond the one-sentence purpose.

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 signal readOnly, idempotent, and non-destructive behavior. The description adds useful context by specifying the state perspective (installed MCPs, connection status, accounts, catalog counts), which goes beyond the fact that it is a safe read operation. No contradictions exist.

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

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

The description is a single well-formed sentence that names the result and enumerates the concrete payload dimensions. Every phrase adds information, and there is no repetition of schema or annotation data.

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

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

Given zero parameters, no output schema, and clear annotations, the description is nearly complete: it states what is returned and at what granularity. A slight addition explaining that it provides the currently connected, available MCP environment prior to authentication or tool selection could further improve completeness, but the current text is sufficient for a low-complexity 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?

The tool has zero parameters and an empty object input schema, so parameter semantics are inherently simple. The description does not need to explain parameters, and the baseline of 4 is appropriate because the no-parameter interface is fully transparent.

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 identifies a clearly bounded resource: the current toolkit state. It also names the exact outputs (installed MCPs, connection status, accounts, catalog tool counts), which distinguishes it from siblings like show_version or authenticate.

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 when to use it: whenever an agent needs an overview of the toolkit's installed MCPs and their connectivity. It does not explicitly state exclusions or alternatives like 'use show_version for just the version,' so it stops short of a 5.

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