CPFL: Download via link + OCR

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

Annotations already indicate readOnly=false, destructive=false, and idempotent=true. The description adds useful behavioral context beyond annotations: browser-based login, permanent header vs session-only token, and no-args behavior returning a link. No contradiction with annotations is present.

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 sized and structured with 'Best:' and 'Or' to separate options. All included information is relevant to using the tool correctly, though the single long sentence is slightly dense.

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 simple optional-parameter schema and no output schema, the description covers the main invocation modes and the overall auth workflow. A minor gap is that it does not state what happens after submitting a token, but this is not essential for correct 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?

The input schema has one optional 'token' parameter with 0% description coverage. The tool description compensates well by explaining that the token should be a JWT for session-only login and that omitting the token returns the login link.

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 this tool handles authentication for MCP.AI IDE agents, explaining the browser login flow and access token usage. It is specific about the action ('log in', 'copy the access token') but does not explicitly distinguish itself from the sibling tool '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?

It provides clear usage guidance: use the config header for a permanent non-expiring connection, or call the tool with a pasted JWT for session-only login, or call with no args to get the login link. However, it does not explicitly state when not to use this tool or mention alternative sibling 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, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable context about conditional behavior: returns authenticated:true with empty pending[] when connected, and connect_url plus per-install URLs when credentials are missing. This goes beyond annotation coverage without contradicting 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?

Two sentences, front-loaded with 'Returns connection status and URLs,' and every sentence adds meaningful behavioral detail. No wasted words.

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

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

For a tool with no parameters and strong annotations, the description covers the primary return states and output URLs. It does not address partial connection scenarios (some providers connected, others missing), but overall it is adequate for the tool's 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?

Tool has zero parameters, so parameter semantics are trivially satisfied and schema coverage is 100%. Baseline of 4 is appropriate; no additional parameter explanation is 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?

Description clearly states it returns connection status and URLs, with specific details about authenticated:true and connect_url outputs. This distinguishes it from siblings like authenticate (which performs auth) and show_version (which shows version 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 use for checking connection status, but does not explicitly state when to use it versus alternatives or when not to use it. It describes response states but no direct guidance for selecting this tool over others.

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. The description adds meaningful behavioral context beyond those: it involves downloading via link and OCR, requires no platform credentials, costs prepaid credit per query, and involves only non-confidential official data under LGPD responsibilities. This gives the agent a clear safety and cost profile.

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 action in the first clause. Each sentence adds non-redundant context about hosting, payment, data classification, and LGPD, though the legal phrasing could be tightened for more direct invocation guidance.

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 provides useful high-level context about official source, payment, credentials, and data sensitivity, which is especially valuable since there is no output schema. However, it does not describe what the returned information actually includes, nor clarify the optional 'documento' parameter, leaving notable gaps for correct 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%, so the description must compensate. It references the 'link' parameter through 'Download via link', but it never explains the optional 'documento' parameter, its format, or its purpose. The agent cannot reliably determine what to pass for 'documento' from the description alone.

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: 'Download via link + OCR, consulta em fonte oficial' for CPFL. It identifies the specific resource (CPFL) and action (consult via official source), and it is clearly distinct from the sibling tools, which are generic platform tools like authenticate 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 provides context about how the tool is hosted, that no platform credentials are needed, and that each query is paid with prepaid credit, which helps set expectations. However, it never explicitly states when to use this tool versus an alternative or provides exclusion criteria; usage is only implied by the CPFL-specific scope.

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 critical behaviors: invoke works even when the MCP is not installed, runs one-off without bloating the tool list, and requires owner/admin for writes. It also explains that invoke returns a connect link for credentials and a checkout/top-up link for billing, which goes beyond the annotations (which only note readOnlyHint false). 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 dense but not redundant; each sentence adds value, covering the core flow, key edge cases, permissions, and the prompt library. It is long, but the complexity of the tool justifies it. A more structured layout (e.g., bullets) would improve readability, but the content 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?

The description covers the main actions and their outcomes: describe returns a full profile, get_prompt returns text with variables filled, publish returns a shareable link. It also addresses permissions, auth, billing, and the prompt library. However, some actions like subscribe, cancel, resume, and list_tools are mentioned but not fully detailed, and there is no output schema to supplement. Given the tool's complexity, it is reasonably complete but has 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?

The description gives meaning to key parameters: action is explained through the flow, tool_id is specified as the target for invoke, and prompt_slug/prompt_vars are implied by the prompt library description. However, with 23 parameters and 0% schema coverage, many parameters (limit, immediate, tier_slug, conversation, cancel_reason) are left unexplained. The core parameters are well-covered, but not the full set.

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

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

The description clearly states the tool is the official mcp.ai marketplace — a catalog and runtime for MCPs. It explicitly says 'the in-platform catalog of every MCP/tool, AND the way to run them', which distinguishes it from siblings like authenticate or show_version. It also explains the core action flow (search → describe → invoke), giving a precise and comprehensive purpose.

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

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

The description provides explicit when-to-use guidance, such as 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT'. It also differentiates list_tools as 'what is callable right now' and request_mcp for when nothing fits. The distinction between invoke and install is particularly clear, with alternatives and exclusions included.

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 supply the side-effect and idempotency information via readOnlyHint=false and idempotentHint=true. The description adds a useful behavioral clue about including recent messages for reproduction, but it does not disclose what happens after submission, whether conversations are transmitted, or any consequence of duplicate reports.

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 efficient sentence that is front-loaded with the action, then adds a single practical requirement. There is no fluff or repeated information.

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

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

Given that there is no output schema and only three properties, the description is enough to invoke the tool for a basic bug report, but it lacks return behavior, error/response expectations, and clear `context` semantics. It's adequate functionality, but not genuinely 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 description coverage is 0%, so the description is the sole source of meaning. It clarifies that `conversation` should contain recent messages, leaving `message` implicitly as the user-facing report text and `context` unexplained. It even describes `conversation` as an 'array' while the schema says the property is a string with default '[]', causing ambiguity.

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 clear verb and scope: 'Report a bug, missing feature, or send feedback.' This is specific enough to distinguish it from sibling tools like `connect`, `marketplace`, 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?

The intended use case is implied—use this when the user wants to report a bug or send feedback—but the description does not explicitly state when to choose this tool over alternatives, nor does it provide exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds the specific scope (platform and adapter versions) and implies it returns current values. It doesn't mention return format or any additional behavior, but with strong annotations this is acceptable.

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 sentence, 10 words, states the essence without fluff. The description is 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 version-query tool with no parameters and strong annotations (readOnly, idempotent, non-destructive), the one-line description fully covers what the tool does. No output schema is needed for such a straightforward informational call.

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 there is nothing to explain. The baseline for 0 parameters is 4, and the description doesn't need to compensate for schema 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 uses a specific verb 'show' and resource 'MCP platform and adapter versions', clearly distinguishing it from sibling tools like authenticate or connect. It precisely states 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?

No explicit guidance on when to use this tool versus alternatives, but as a simple version query its purpose is self-evident. It doesn't mention when not to use it or provide alternatives, but the context is clear enough for basic retrieval tasks.

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, so the description adds value by specifying what 'toolkit state' includes. It goes beyond annotations by detailing the exact return contents, though it does not describe the return format or potential performance characteristics.

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

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

The description is a single, well-structured sentence that front-loads the main action and then lists the returned components. Every phrase adds valuable information, with no wasted words.

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

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

For a simple no-parameter informational tool, the description adequately covers the returned content. It does not detail the exact output schema, but the enumeration of items is sufficient for an agent to understand what to expect. Since there is no output schema, a slightly richer description of return structure could have been given, but it is not a critical gap.

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 schema coverage is trivially 100%. The description correctly adds no parameter-specific content, and the baseline score of 4 applies given the absence of 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 clearly states the tool's purpose: 'Returns the current toolkit state' and enumerates specific contents (installed MCPs, connection status, accounts, catalog tool counts). This specific verb+resource is distinct from sibling tools like show_version 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 usage as an informational read-only tool, but it does not explicitly state when to use it versus alternatives or mention any exclusions. Sibling tools like connect or authenticate have different purposes, but no direct comparison is provided.

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