Receita Federal: Agenda Tributária

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

Annotations already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds valuable context: it explains that no-args returns a login link, token-based calls create a session-only login, and config headers yield a permanent non-expiring connection. This goes beyond the boolean hints by describing the auth flow and token lifecycle, though it doesn't detail return formats or error behavior.

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 three sentences with no wasted words. It front-loads the audience and purpose, then follows with two concrete usage paths. Every phrase adds value: audience, auth flow, permanent vs session modes, and parameter usage. It is dense but readable.

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 a single optional parameter, no output schema, and helpful annotations, the description covers all essential behavior: how to initiate login, how to pass a token, and the distinction between permanent configuration and session-only token usage. It is complete for an authentication 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?

The schema only defines 'token' as a string with no description. The description fully compensates: it identifies the token as a JWT, explains it must be pasted by the user, and contrasts it with the no-args case that returns a link. This gives complete semantic meaning to the optional token parameter and its omission.

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: authenticate to MCP.AI for IDE agents by logging in via browser and using an access token. It distinguishes this from a generic 'connect' by specifying the exact authentication flow and two modes (permanent via config header, session-only via token). The verbs 'log in', 'copy the access token', and 'call with { token }' are specific and 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 gives explicit when-to-use guidance: permanent connections should be set via config header, session-only logins should use the token argument, and calling with no args retrieves the login link. It advises the 'best' approach and implicitly tells the agent when NOT to rely on the tool for permanent auth. No exclusions against sibling tools are needed because the purpose is unique.

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 adds behavioral context beyond the annotations by explaining the two return scenarios (all connected vs. missing credentials). It discloses the nature of the output without introducing side effects, aligning with the readOnly and idempotent hints.

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 at two sentences, efficiently covering the main purpose and edge cases. It avoids unnecessary detail while remaining clear.

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 there is no output schema, the description fully specifies the return value format and both possible states. It is self-contained and leaves no ambiguity about what the tool returns.

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 no parameters, so coverage is 100%. The description does not add any parameter-specific information, which is acceptable but does not elevate the score beyond the baseline.

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 elaborates on the two possible outcomes. It is specific about the resource and action, though it does not explicitly differentiate from sibling tools like 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 when to use the tool (to check connection status) but does not explicitly state when to prefer it over alternatives or provide exclusionary guidance. It lacks explicit 'when not to use' or references to 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?

Beyond the annotations, the description discloses critical behaviors: invoke runs MCPs without installation, returns connect/checkout links for auth/payment, and writes require specific permissions. It also explains the prompt library flow, providing extensive operational context.

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 lengthy but every sentence adds value, covering the diverse action set. It is front-loaded with the core flow (search→describe→invoke) and structured by capabilities. It could be tightened but is appropriately sized for 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?

For a tool with 23 parameters and no output schema, the description explains the main flows and edge cases (auth, payment, permissions, prompt sharing). It does not detail exact return shapes but provides sufficient guidance 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 schema_description_coverage at 0%, the description must explain parameters. It does so for core ones like action, mcp_id, tool_id, arguments, and prompt-related fields, but not exhaustively for all 23 params. It gives enough to understand the main workflows.

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: it is the official marketplace for MCPs/tools, offering both discovery and execution. It explicitly distinguishes from sibling tools by detailing unique features like invoke-without-install and the prompt library, making the purpose 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 guidance on when to use each action, contrasting invoke vs install, listing_tools, subscribe/cancel, and others. It names alternatives (request_mcp when nothing fits) and clarifies prerequisites like workspace owner/admin for writes.

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 the tool is read-only, idempotent, and non-destructive, so the description does not need to repeat these. The description adds useful context about payment requirements (pre-paid credits) and data privacy (LGPD), but does not detail potential limitations like data availability delays or rate limits.

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 packs multiple pieces of information (official source, hosting, payment, data privacy) but lacks structure. It front-loads the tool's purpose but then mixes compliance and payment details, making it slightly dense. No unnecessary repetition, but could be better 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?

Given the tool is simple (2 params, read-only, no nested objects), the description covers key operational aspects. However, it does not explain the output format or any potential error conditions (e.g., invalid month/year), which could affect usability. The lack of an output schema increases the need for description clarity, but the description is adequate for basic use.

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 only defines 'mes' and 'ano' as strings without any description of expected formats (e.g., 'MM' vs 'January' or 'AAAA' vs 'YY'). The description provides no additional guidance on parameter values, leaving agents to guess the format. Since schema coverage is 0%, the description should compensate but does not, resulting in a baseline score of 3 due to the minimal parameter count.

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 tool as consulting the Brazilian Federal Revenue's tax calendar from an official source. It distinguishes itself from generic tools but does not explicitly contrast with any sibling that might offer similar tax data.

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 schedule information, but it does not specify when to use this tool versus alternatives, as there are no sibling tools with similar functionality. It also does not mention any prerequisites beyond having pre-paid credits.

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 provide idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds the reproduction requirement but does not mention side effects, error behavior, response format, or retry implications. For a low-complexity feedback tool, this is acceptable but not rich.

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 short sentences that front-load the purpose and immediately provide actionable parameter guidance. Every sentence earns its place, and there is no filler or repetition of the name/title.

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 tool with three parameters, no output schema, and harmless annotations, the description covers the primary action and the key reproduction input. It could mention expected result or error handling, but the required fields and defaults make this a fairly complete description.

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 adds meaning to the 'conversation' parameter by saying it should contain recent messages for reproduction, which is useful since the schema merely says 'string.' However, it does not explain 'context' or clarify that 'conversation' should be a JSON-encoded string despite being called an 'array.'

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 with a specific verb and resource: 'Report a bug, missing feature, or send feedback.' This is distinct from all sibling tools, which are unrelated actions 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?

It tells the user when to use the tool (to report a bug/feedback) and gives a key usage instruction: 'Include the conversation array with recent messages for reproduction.' It does not explicitly list exclusions or alternatives, but no sibling tool plausibly competes with this one.

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, and the description aligns with these by saying 'Show', implying a non-destructive read operation. No additional traits are disclosed, but annotations cover the key aspects.

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 with no superfluous words, directly stating the tool's 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?

Given there are no parameters and no output schema, the description fully explains what the tool does. No additional context is required for an agent to invoke it correctly.

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 no parameters and the schema covers 100% of them (none). The baseline for high coverage is 3, and the description does not need to add parameter details since there are none.

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 the tool shows MCP platform and adapter versions, using a specific verb 'Show' and resource, which distinguishes it from sibling tools like authenticate, connect, or report_bug.

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?

While there is no explicit 'when to use' guidance, the purpose is self-evident as a version check, and no alternatives exist among siblings. The description implicitly indicates use when version information is 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=true and destructiveHint=false, so the description does not need to repeat safety. It adds value by precisely listing the returned information (installed MCPs, status, accounts, catalog counts), which goes beyond the annotations. 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?

A single, front-loaded sentence that completely describes the tool's output without any filler. Every word earns its place, listing the specific components of the returned state.

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 (no parameters, no output schema), the description fully covers what the agent needs to know: what the tool returns. The sibling context and tool name reinforce the purpose, making the description complete 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, and schema coverage is 100% (vacuously). Baseline for zero parameters is 4, and the description does not introduce any parameter-related ambiguity. No parameter documentation 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?

The description uses the specific verb 'Returns' and clearly specifies the resource (toolkit state) and scope (installed MCPs, connection status, connected accounts, catalog tool counts). It distinguishes itself from siblings like connect and authenticate by being purely informational.

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 this tool: when you need to inspect the current toolkit state. However, it does not explicitly mention alternatives or when not to use it, but given the sibling action tools, the context is clear.

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