Receita Federal PGFN: Lista de Devedores

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

The description discloses key behavioral traits: permanent non-expiring vs session-only login, and that no-arg calls return a link. Annotations already indicate readOnlyHint:false and idempotentHint:true, and the description is consistent with those. It adds context about the two authentication flows, though it could mention what happens on invalid tokens or the actual return value.

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 and densely packed with useful information, essentially no fluff. The main weakness is the awkward phrasing 'MCP.AI for IDE agents (Cursor, etc.): log in in the browser' which could be streamlined. Overall, it earns its place with high information density.

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 tool has one optional parameter and no output schema, so the description adequately covers the essential flows. It explains both authentication modes and the no-arg call, which is sufficient for typical usage. It might benefit from a brief note about response or error behavior, but this is not critical given the tool's simplicity.

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?

Despite 0% schema description coverage, the description explains the token parameter is a JWT fetched after user login ('copy the access token', 'call with { token: "<jwt>" }') and clarifies the no-arg behavior. This compensates well for the minimal schema, though it could add details about token format validation or error cases.

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 the tool's purpose is authentication for MCP.AI with instructions to 'log in in the browser, copy the access token.' Although the opening phrase is a bit convoluted, the verb+resource is clear and distinct from siblings like connect or marketplace. It could be more direct but 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 provides explicit when-to-use guidance: permanent vs session login, including exactly when to call with a token ('call with { token: "<jwt>" } after the user pastes') and when to call with no args ('or with no args to get the link'). It even recommends the best practice with 'Best: add it to this server's config.' This exceeds baseline by giving actionable decision-making instructions.

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 mark this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond that by specifying return-conditionals: authenticated:true with empty pending[] when connected, and connect_url plus per-install URLs when credentials are missing. Since there is no output schema, this return-shape disclosure is valuable.

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 the core purpose, and no filler. The conditional states are described efficiently and every clause adds concrete information about behavior or return values.

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 connection-status tool, this description is complete. It covers the primary success state and the missing-credentials state, and the annotations cover safety and side-effect expectations. No output schema exists, but the description supplies the key return distinctions an agent needs.

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 the schema provides no semantic guidance and the description does not need to explain parameters. A baseline of 4 is appropriate because the description fully covers the tool's observable input surface—there is nothing missing.

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: returning connection status and URLs. It also distinguishes itself from siblings like authenticate by focusing on status reporting rather than the auth flow itself.

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 the tool by outlining two distinct states (all connected vs. missing credentials), which helps an agent decide if connection checking is appropriate. It does not explicitly name alternatives or exclusion criteria, but the use case is clear enough from the content.

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 carries a heavy transparency burden beyond the sparse annotations (readOnlyHint=false, destructiveHint=false) and fully delivers. It discloses that invoke runs one-off without installing, that writes require workspace owner/admin, that credential needs surface as connect links, and that empty wallets trigger checkout links. No contradiction with annotations; instead it enriches them with permission scoping and side-effect semantics.

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?

Every sentence earns its place and the most important info is front-loaded, but the entire description is one dense, unbroken paragraph with no visual structure — no bullets, line breaks, or section headers separating the marketplace flow from the prompt library. For a tool with 14 actions and 23 params, this density hurts scannability even though nothing is wasted. Adequate but poorly organized.

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 high-complexity tool (23 params, 14 actions, no output schema), the description covers remarkably much: full action taxonomy, install-vs-invoke tradeoffs, permission requirements, billing/credential handling, and installed_in_toolkit vs installed_in_workspace flags. It describes notable return products (connect links, checkout links, shareable mcp.ai/p/<slug> links). Minor gaps: it does not describe return structures for search/describe or list_tools results, which the absent output schema leaves unexplained, keeping it one point below 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?

With 0% schema description coverage across 23 parameters, the description must compensate significantly. It adds meaning to the critical action parameter by enumerating all 14 behaviors and explains the functional role of tool_id and mcp_id in the describe/invoke flow, plus prompt_vars in get_prompt. However, many parameters (conversation, cancel_comment, report_context, prompt_targets, immediate, tier_slug) receive no semantic explanation, leaving gaps for an already undocumented schema. Partially compensates but not fully.

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 a precise statement: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It defines the core search→describe→invoke flow and differentiates from siblings by naming alternatives (authenticate, connect) implicitly through its marketplace scope. Even though it also covers the prompt library sub-domain, the primary purpose is unmistakably stated.

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?

Extensive explicit guidance is provided: the core flow ('action=search discovers MCPs by intent → describe returns one MCP's full profile... → invoke RUNS that tool'), explicit when-not guidance ('prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT in the active toolkit'), and when list_tools is appropriate ('lists what is callable right now'). It even handles edge cases like connect links and checkout/top-up retry flows, giving the agent clear decision criteria.

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, so the description doesn't need to restate this. However, the description adds important context about billing (prepaid credits) and legal framework (LGPD), which is valuable. But there's ambiguity: it says 'sem credenciais da plataforma' (without platform credentials) which could confuse agents about authentication requirements, and doesn't clarify whether the query is synchronous, rate-limited, or returns partial data without credentials. The LGPD comment about data controller responsibilities is relevant but not a behavioral trait of the tool itself.

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 relatively concise, fits in 3 sentences, and front-loads the core purpose. Every sentence adds some value: what (debtors list), how (official sources, prepaid credit), and legal context (LGPD). The text is borderline long but manages to pack relevant information in a scannable paragraph. Minor reduction could improve, but it's well below the verbosity threshold.

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 query tool with 2 flat params and no output schema, the description covers the basics but misses key aspects: the semantics of the two params (both identifying numbers), expected output shape (debtor list, but no structure), and error conditions (what if CPF not found?). The legal disclaimer is unique but takes up space that could have clarified the input/output contract. The tool could be idempempotent and safe to call, which is already annotated, reducing the burden on the description, but the lack of param semantics is a notable 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?

Schema description coverage is 0% and the description adds no parameter-level details. The description doesn't clarify the relationship between 'cpf' and 'cnpj' parameters (are they mutually exclusive? Both required? Which takes precedence?). Information such as minimum/maximum lengths (11 for CPF, 14 for CNPJ) or format validation rules is missing. The phrase 'pague por consulta com crédito pré-pago' implies a costly operation, which should have prompted explanations about when one parameter matters over the other.

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 identifies the resource (Brazilian Federal Revenue/PGFN debtors list) and mentions querying official sources, but the verb is weak ('consulta' is implied rather than a concrete action like 'search' or 'list'). It lacks a clear opposition to sibling tools, of which most are unrelated (authenticate, connect, marketplace). The purpose is inferable but not precisely stated as a strong verb+direct object structure.

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 some context (prepaid credits, no platform credentials, LGPD compliance) but doesn't address when to use this specific tool over alternatives or when to query CPF vs CNPJ. No explicit instructions on when to call this tool, input validation rules, or what the query means for the Brazilian context. The description focuses on legal/commercial terms rather than practical usage guidelines.

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 idempotentHint=true, readOnlyHint=false, and destructiveHint=false, covering basic safety traits. The description does not add extra behavioral context such as what happens after submission (e.g., logging, notification) or any side effects. It adds a hint about including conversation data, but that is more about parameters than tool behavior. The description is not contradictory to any annotation, so a score of 3 is appropriate given the bar is lowered by 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 sentence that front-loads the purpose and includes a practical usage hint. Every word earns its place with no fluff, making it highly 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's simplicity (3 parameters, no output schema, no nested objects), the description covers the core use case. However, it lacks details on the 'context' parameter and does not explain expected message format or any post-submission behavior. While annotations provide safety info, the description is minimal and leaves some ambiguity, resulting in a moderate completeness score.

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 explaining all parameters. It only explicitly mentions the 'conversation' array ('Include the conversation array') and implies 'message' as the main content, but completely omits the 'context' parameter. The schema provides defaults for context and conversation, but the description does not elaborate on their purpose. With 0% coverage, this is a significant gap, hence a score of 2.

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 with clear scope. It is obviously distinct from siblings like authenticate, marketplace, or show_version, so it ticks the differentiation box.

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 clear context for when to use the tool (bug reporting, feature requests, feedback) and even provides a usage hint about including the conversation array. It does not explicitly mention exclusions or alternatives, but the sibling list makes it obvious that other tools serve different purposes. This is adequate 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=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety traits. It adds value by specifying the exact content shown ('MCP platform and adapter versions'), which goes beyond the annotations. No contradictions detected.

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 immediately states the tool's purpose. It is front-loaded with the verb and resource, contains no filler, and every word earns its place.

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 extreme simplicity of the tool (no parameters, no output schema, and annotations covering side effects), the description is fully complete. It tells the agent exactly what to expect: the current versions of the platform and adapter. No additional detail would meaningfully improve agent decision-making.

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 the baseline is 4 per the guidelines. The description adds no parameter information, but none is needed since the schema coverage is 100% and there are no inputs to document.

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: 'Show the current MCP platform and adapter versions.' It uses a specific verb ('show') and specific resource ('MCP platform and adapter versions'), distinguishing it from sibling tools like toolkit_info by specifying exactly what versions are returned. There is no ambiguity or tautology.

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 clear context for when the tool is used (to view current versions), and it is self-evident that a user would call it when they need version information. It does not explicitly mention exclusions or alternatives, but given the tool's simplicity and uniqueness among siblings, this is not a significant gap.

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, so the agent knows it's a safe read. The description adds value by enumerating the specific return fields (installed MCPs, status, accounts, catalog counts), which goes beyond the generic read-only annotation. It does not contradict annotations and provides context on what to expect without describing output format (which is unnecessary since no output schema exists).

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, efficient sentence that front-loads the main purpose ('Returns the current toolkit state') and then lists the specific details. Every word contributes value; there is no fluff or redundancy. It is appropriately sized for a parameterless read-only 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?

Given the tool's low complexity (no parameters, no output schema) and strong annotations that declare read-only and idempotent behavior, the description fully covers what the tool returns. It names all key output elements, so the agent knows exactly what information will be available. No additional behavioral details are needed for this level of 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 tool has zero parameters, so the schema already fully describes the input (there is none). The baseline for 0 parameters is 4, and the description does not need to add parameter-specific semantics since there are none. It accurately implies the tool takes no input.

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 the current toolkit state, and specifies exactly what that includes: installed MCPs, their connection status, connected accounts, and catalog tool counts. It distinguishes itself from siblings like show_version (version info) and connect (likely to establish connections) by focusing on overall state rather than a specific action or subset.

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 tool is used to inspect the toolkit's state, but it does not explicitly say when to use it versus alternatives like authenticate or connect. There's no direct guidance on prerequisites or when to avoid using it. It's clear that it's for checking status, but no explicit 'when not to use' or alternative recommendations. Given the sibling list, this is somewhat implied but not stated.

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