Receita Federal: PGFN (CND Federal) - Segunda Via

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

The description goes beyond the annotations by explaining the behavior in terms of permanent vs. session-only login and the link retrieval. It does not explicitly state side effects like token storage, but it implies the difference between the two methods, adding useful context for the agent.

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, capturing the essential information in two sentences without excessive verbosity. It is well-structured, offering both the permanent and session methods clearly, though a slight reduction in redundant phrasing could improve it.

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 absence of an output schema, the description sufficiently explains what the tool does and how to use it, including the two usage paths and the effect of the token parameter. It does not explicitly describe the return value when a token is passed, but the context implies it confirms authentication, which is adequate for an agent.

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 'token' as an optional string, but the description thoroughly explains its purpose and usage: passing it after the user pastes, or omitting it to get the link. This provides complete parameter semantics that are absent from the schema, making the tool easy to use correctly.

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 that this tool is for authenticating to the MCP server, describing the login process and token handling. It distinguishes itself from sibling tools like 'connect' by focusing on the authentication step rather than connection establishment.

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 explains when and how to use the tool: it provides two options (permanent config via header vs. session-only paste) and specifies that calling with no args returns a link. This gives clear usage guidance and alternatives, making it easy for an agent to decide when to invoke it.

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 agent knows it's a safe read operation. The description adds value by explaining the two states (authenticated vs. missing credentials) and the presence of connect_url, which is useful context beyond the annotations. However, it doesn't detail the exact structure of the response or any potential side effects, but given the annotations, a 3 is appropriate.

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, front-loaded with the main purpose, and provides concrete details about the two possible outcomes. Every sentence adds value, and there is no fluff. It is concise and well-structured.

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 has no parameters, no output schema, and simple annotations, the description is quite complete. It explains the two states and what URLs are returned. It could mention the exact format of the response or the meaning of 'pending[]', but for a status-check tool, this is sufficient. The sibling tools like authenticate and toolkit_info are not explicitly referenced, but the description's clarity makes it complete enough.

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 the schema coverage is 100% (vacuously). The description doesn't need to explain parameters, but it does explain the output semantics (authenticated:true and empty pending[] vs. connect_url), which is valuable. Since there are no parameters, the description's focus on output behavior compensates for the lack of parameter info, earning a 4.

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, and distinguishes between all-connected and missing-credentials scenarios. It is specific about the resource (connection status) and the action (returns), and it differentiates from siblings like authenticate and toolkit_info by focusing on status rather than initiating auth or general 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 when to use it (to check connection status) but does not explicitly state when not to use it or mention alternatives. It provides context about the two possible outcomes, which helps the agent decide, but lacks explicit guidance on when to prefer this over authenticate or other 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?

Discloses behavioral traits beyond annotations, such as writes requiring workspace owner/admin, invoke running one-off without installation, and returning connect/checkout links. This adds significant context beyond readOnlyHint=false and openWorldHint=true.

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 long but well-structured, following a logical order from core flow to permissions to prompt library. Every sentence adds information, yet it is not as terse as the ideal two-sentence example. The length is justified by the tool's 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 high complexity (14 actions, 23 params, no output schema), the description is remarkably complete. It covers core flow, permissions, auth/payment edge cases, and the prompt library, providing sufficient context for correct agent 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?

With 0% schema description coverage, the description compensates by explaining key parameters like action, mcp_id, tool_id, and arguments within the flow. However, it omits details for limit, immediate, tier_slug, and other parameters, so it does not fully cover all 23.

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, covering both discovery and execution of MCPs. It distinguishes itself from siblings by being the central catalog and runner, and enumerates specific actions and flows (search→describe→invoke).

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?

Explicitly provides usage guidance: 'prefer invoke for a single/occasional use' and 'use install only to make an MCP PERMANENT', plus the core flow with alternatives. It also explains when to use search vs describe vs invoke, and that install is for permanence.

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 (readOnlyHint, idempotentHint, etc.), the description adds crucial operational details: payment model ('pague por consulta com crédito pré-pago'), hosting context ('Hospedado pela plataforma, sem credenciais da plataforma'), data non-confidentiality ('não é dado sigiloso'), and LGPD compliance responsibilities. This exceeds annotation-only 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, well-structured paragraph that front-loads the core purpose and quickly moves to operational and legal notes. At ~50 words, it is concise but packs in multiple clauses. It could be slightly more scannable, but it remains effective.

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 read-only tool with no output schema, the description covers billing, data source, and legal accountability, which is helpful. However, it omits any parameter-level guidance or request construction details, which are critical for an API with three parameters and unclear combinations. It is adequate but has clear 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?

With 0% schema description coverage, the description needed to explain `cpf`, `cnpj`, and `birthdate`, but it does not mention them at all. There is no information about validation rules, optionality (none are required), or relationships (e.g., cpf vs cnpj). Users are left guessing parameter meaning, which is a significant gap.

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 with a specific verb ('consulta') and resource ('PGFN (CND Federal) - Segunda Via'). It specifies consultation of official Brazilian sources, distinguishing it from generic sibling tools like 'authenticate' and 'connect'. The scope is unambiguous.

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 querying official tax data (e.g., 'consulta em fonte oficial') and notes practical conditions like payment and no credentials. However, it does not explicitly compare with alternatives or provide when-to-use/not-to-use guidance relative to other tools, though siblings appear functionally distinct.

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 the safety profile (readOnlyHint false, destructiveHint false, idempotentHint true). The description adds little beyond stating it reports feedback—no mention of side effects, rate limits, or internal behavior. It does not contradict annotations, but also does not enrich them meaningfully.

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 concise, two sentences, with no fluff. The primary purpose is front-loaded, and the additional instruction about the conversation array is necessary. Every word adds value.

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 lack of schema descriptions and no output schema, the description should clearly define all parameters and expected behavior. It only mentions 'conversation' for reproduction and leaves 'message' and 'context' vague. For a tool with only 3 parameters, this is insufficient for an agent to invoke it correctly without guessing.

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 explicitly explains the 'conversation' parameter ('Include the conversation array with recent messages for reproduction') but leaves 'message' and 'context' undescribed. Even though 'message' is required, the description implies it is the feedback text but does not clarify 'context.' Overall, only one of three parameters is partially explained.

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.' It uses a specific verb-resource pair and is unambiguous. Sibling tools like authenticate or connect are unrelated, so no differentiation is 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 implies usage for bug reporting but does not explicitly state when to use this tool versus alternatives (none needed). It does instruct the user to include the conversation array, which gives context on the required input, but lacks explicit when-to-use or when-not-to-use 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 declare readOnlyHint and destructiveHint, so safety is covered. The description adds the output scope (platform and adapter versions), providing concrete behavioral information beyond what annotations convey. It doesn't mention any edge cases, but for a read-only version 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, clear sentence that front-loads the purpose with no filler. Every word contributes value.

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 low complexity (0 params, no output schema), the description fully explains what the tool does and what it returns. Annotations cover safety, making the tool sufficiently well-documented.

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 0 parameters, so schema coverage is trivially 100%. Per rubric, 0 parameters earns a baseline of 4; the description doesn't need to add parameter info. It correctly mentions what the tool returns, which is the only relevant semantic.

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 shows current MCP platform and adapter versions, using specific verb 'Show' and resource 'versions'. It distinguishes itself from sibling tools (authenticate, connect, etc.) which serve different functions.

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 name and description – when you need to know platform/adapter versions. However, no explicit when-to-use or alternative guidance is provided, though given the tool's simplicity, the implication is sufficient.

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, idempotent, and non-destructive behavior. The description adds no extra behavioral context such as side effects, rate limits, or dependency notes, but it does not contradict the annotations either.

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, concise sentence that is front-loaded with the main action ('Returns the current toolkit state') and immediately details the specific components, achieving high clarity without unnecessary 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?

The description lists all the key pieces of information returned (installed MCPs, connection status, accounts, catalog tool counts), which is sufficient for a simple getter. It doesn't specify data format or ordering, but that is not critical for a state snapshot.

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 schema coverage is 100% (empty schema). The description correctly omits parameter details since none exist, aligning with a baseline score of 3.

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 and output contents, specifying 'installed MCPs, their connection status, the accounts connected to each one, and how many catalog tools each exposes', which is specific and directly conveys the 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 does not indicate when to use this tool versus alternatives. It only describes what it returns without guidance on scenarios or comparisons to sibling tools like authenticate or connect.

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