Receita Federal: PGFN (CND Federal) - Lista Segunda Via

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

Adds meaningful behavioral context beyond annotations: describes permanent vs. session-only login, how the token is used, and that no-args calls return a link. Annotations include idempotentHint=true, which aligns with repeated calls to obtain a link or update auth, with no contradiction.

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?

Three sentences, each earning its place: purpose, recommended permanent setup, and session-based alternative. Slightly dense but well-structured and front-loaded with the core purpose.

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?

Covers both primary usage modes (obtaining link, submitting token) and explains persistence differences. Without an output schema, it could mention what happens after token submission (e.g., response format), but overall the description is sufficiently complete for an auth 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 has a single 'token' string with 0% description coverage, but the description fully compensates by explaining it is a JWT pasted by the user and showing exact invocation patterns: { token: '<jwt>' } or no args. This gives clear meaning to the parameter beyond the bare 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 clearly states the tool's purpose: 'log in in the browser, copy the access token' for MCP.AI IDE agents. It distinguishes itself from siblings by focusing specifically on authentication flows (login link and token submission) rather than connection or marketplace operations.

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 alternatives: adding the token as a header for a permanent connection, pasting it for session-only login, or calling with no args to get the login link. It gives a recommended best approach but does not explicitly mention when not to use this tool relative to 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 establish readOnly, idempotent, non-destructive behavior. Beyond that, the description adds meaningful behavioral detail about conditional response states: authenticated:true and empty pending[] when fully connected, and connect_url plus per-install URLs when credentials are missing. This supplements 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 compact and front-loaded, beginning with the core purpose in the first sentence. Every subsequent sentence provides specific conditional behavior, with no filler or redundant content. It is appropriately sized for a simple parameterless 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 parameterless status tool with strong annotations, the description covers the two key states: fully connected and missing credentials. It provides specific return indicators (authenticated, pending[], connect_url). However, it does not fully define the structure of pending[] or address a possible partial-connection state, leaving slight ambiguity.

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, which reduces the need for parameter documentation. The description correctly avoids discussing parameters, and with no schema fields to describe, a baseline of 4 is appropriate.

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, using the specific verb 'Returns' and defining the resource. It distinguishes itself from likely siblings like 'authenticate' by emphasizing this is a status/read operation, not an action that establishes a connection. However, it does not explicitly call out sibling alternatives, so it falls short of a top score.

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?

Usage context is implied rather than stated directly. The description indicates you can check whether all providers are connected and get URLs when credentials are missing, which implies a status-check use case. There is no explicit guidance on when to use this tool instead of alternatives, nor any 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?

With annotations limited to readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false, the description carries the burden and exceeds it substantially. It discloses the non-obvious one-off execution trait ('invoke works even when the MCP is NOT installed... without bloating the tool list'), auth requirements (connect link when credentials needed), billing behavior (checkout/top-up link when wallet empty), and permission constraints (writes require workspace owner/admin). No contradiction with annotations 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 information-dense and every sentence adds value, which is good, but it is formatted as one continuous wall of text with no structural aids—no bullets, no section separators, no front-loaded summary of the action categories. For a tool with 14 actions and 23 parameters, this density is somewhat justified, but scanning for specific action guidance is difficult. It deserves credit for zero fluff, but loses points on scannability.

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 complexity (23 params, 14 actions, no output schema), the description is remarkably complete on behavior: it covers the discovery-to-execution flow, edge cases (auth, payment, retry semantics, one-off vs permanent install), permission scoping, and the prompt-library feature. It lacks detail on output/return shapes and some parameter specifics, but for a tool of this scale covering the full action surface and behavioral quirks, it is thorough. Minor gaps on return value documentation prevent a 5.

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 for 23 parameters. It explains the action enum well (search, describe, invoke, install, search_prompts, get_prompt, publish_prompt are all given behavioral context in the flow). However, many parameters remain undocumented in both schema and description: arguments (format/expectations), tier_slug, immediate, prompt_vars, conversation, prompt_targets, request_details, and cancel_reason are not explained at all. The action semantics are well covered, but the heavy parameter load is only partially compensated.

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 defines the tool as 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It uses a specific verb-resource structure, thoroughly differentiates from siblings (authenticate, connect, report_bug, show_version, toolkit_info) by positioning itself as the discovery-and-execution hub, and articulates distinct sub-capabilities (search/describe/invoke/install) for the multi-action design.

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 lays out the core flow: 'action=search discovers MCPs by intent → describe returns one MCP's full profile... → invoke RUNS that tool.' It gives a direct when-to-use directive: 'prefer invoke for a single/occasional use; Use install only to make an MCP PERMANENT in the active toolkit.' It also names when not to use certain paths (invoke returns connect/checkout links, then retry) and covers the prompt-library sub-flow, giving clear alternative guidance per 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 read-only, idempotent, non-destructive behavior. The description adds value beyond annotations by disclosing payment per query, lack of platform credentials, public data nature, and LGPD responsibility, enriching the agent's understanding of operational and legal context without contradiction.

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 compact paragraph with each sentence adding substantive info (purpose, hosting, payment, data scope, legal note). It is front-loaded with the core purpose and avoids fluff, though it could be slightly more structured for quick scanning.

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 presence of annotations, the description omits crucial details for a 5-parameter tool: it doesn't clarify what data_inicio/data_fim represent (likely date ranges), what the output looks like, or how the query works. The lack of output schema and parameter documentation makes the description incomplete for an agent to use the tool effectively.

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 but provides no explanation for the 5 parameters (cpf, cnpj, birthdate, data_inicio, data_fim). It only hints at CPF/CNPJ via the tool name, leaving required and optional parameters ambiguous, which is insufficient for correct 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 tool queries official sources for 'Segunda Via' of PGFN (CND Federal), identifying the specific resource and action. It distinguishes itself from unrelated sibling tools by focusing on a unique governmental query function, though it could be more explicit about what 'Lista Segunda Via' precisely returns.

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 public official data and mentions payment model, but does not provide explicit when-to-use vs. alternatives or exclude scenarios. Since sibling tools are unrelated, no exclusions are needed, but clear usage context (e.g., intent to obtain a CND duplicate) is missing.

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 idempotent, non-destructive behavior; the description adds the useful requirement to include recent messages for reproduction. However, it does not disclose what happens after submission, such as whether a ticket or report is created.

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 concise sentences, front-loaded with purpose and followed by a single actionable requirement. No unnecessary details 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 low-complexity tool, this is mostly sufficient: purpose, key input guidance, and annotations cover safety. However, it omits semantics for the context parameter and does not indicate what response or acknowledgment the agent should 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?

Schema description coverage is 0%, so the description must compensate. It usefully explains the conversation parameter's purpose, but it leaves message and context unexplained, and 'conversation array' conflicts with the schema's string type.

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 action ('Report') with explicit resources ('bug, missing feature, or send feedback') and includes a reproduction hint. This makes it distinct from sibling tools like show_version and 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?

It clearly states when to use the tool—for bugs, missing features, or feedback—and gives a specific instruction to include the conversation array. It does not mention explicit exclusions or alternatives, but there is little sibling overlap.

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 readOnlyHint, idempotentHint, and destructiveHint. The description adds context by specifying that both MCP platform and adapter versions are returned, which goes beyond the structured annotation information.

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, clearly front-loaded sentence. Every word contributes to understanding the tool with no redundancy or unnecessary complexity.

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 zero-parameter schema and clear annotations, the description is sufficiently complete. It states what is shown—platform and adapter versions—while the annotations cover the safety and idempotence profile.

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 no schema detail or parameter ambiguity to resolve. Baseline parameter score of 4 is appropriate; the description does not need to explain any parameter semantics.

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 'Show the current MCP platform and adapter versions' uses a clear verb and identifies the specific resource. It is understandable but does not explicitly differentiate itself from sibling tools such as '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?

Usage is implied by the description: call this when you need version information. However, it does not explicitly state when to use this tool over possible alternatives, nor does it mention any when-not-to-use 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 declare readOnlyHint=true and destructiveHint=false. The description adds value by detailing what the state includes (installed MCPs, connection status, accounts, catalog tool counts), going beyond the annotation's safety 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?

A single, well-structured sentence conveys the tool's purpose and output details without any filler. Every part of the description is meaningful.

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, the description adequately summarizes the return value (state components). It is sufficiently complete for a zero-parameter, read-only tool, though a hint about the response format could slightly 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 tool has zero parameters, so schema coverage is trivially 100%. No parameter explanations are needed; the baseline of 4 applies.

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: 'Returns the current toolkit state' with specific output components (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from action-oriented siblings like connect and 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 implies usage for inspecting toolkit status, but does not explicitly state when to use it versus alternatives. However, no sibling tool performs a similar read-only state inspection, making its purpose clear from context.

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