Receita Federal: IRPF

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

The description mentions the two authentication modes but does not explicitly state side effects (e.g., whether it stores the token, if it makes network calls, or if calling with no args returns a unique link). The idempotentHint annotation is not reinforced or contradicted, but the description lacks detail about state changes or persistence.

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 bit lengthy but well-organized into two main options (permanent vs. session-based) with clear wording. The structure aids readability without excessive verbosity.

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 the essential steps for authentication, including the two methods and the token's role. It does not explicitly state the output format, but since no output schema is provided, this is acceptable. Overall, it provides sufficient context for an agent to understand how to perform authentication.

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 single parameter 'token' is explained as a JWT obtained from the login process, and its optionality is clarified by the statement that calling with no args retrieves a link. This adds meaningful context beyond the bare schema definition.

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: authenticating with MCP.AI for IDE agents. It explains the login process and distinguishes between permanent and session-based authentication, making the intent specific and not a 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?

Provides explicit usage instructions: how to obtain the token, how to use it (via config header or by passing token directly), and the behavior when called with no arguments (retrieve the login link). This gives clear guidance on when to use each approach.

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, and the description adds useful behavioral context by specifying the exact response structure under different credential states. This goes beyond the annotations, though it doesn't mention any side effects or exact URL formats.

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 highly concise, using two sentences to convey the core behavior and conditional outcomes. Every word adds value, with no fluff 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 simple read-only status tool with no parameters and no output schema, the description adequately covers the main scenarios. It does not describe the structure of URLs or pending array in detail, but this is likely acceptable for 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?

The tool has zero parameters, and the schema coverage is 100%, so the baseline of 4 applies. The description adds no parameter-specific details, but none are needed since there are no inputs.

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 it distinguishes itself from the sibling 'authenticate' by focusing on status rather than the auth flow. It gives specific conditional outcomes (authenticated:true with empty pending[] vs. connect_url for missing credentials).

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 checking connection status but does not explicitly state when to use this versus the 'authenticate' sibling or other tools. It lacks explicit when-to-use or when-not-to-use guidance, so the agent must infer the appropriate context.

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 goes far beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing that invoke runs one-off without installing, returns connect/checkout links, and that install makes permanent changes. It also notes installed-status flags and the prompt library's behavior. This adds substantial behavioral context without contradicting 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 long (about 300 words) but well-structured, starting with the core purpose, then the main flow, followed by invoke specifics, install vs invoke, other actions, and the prompt library. Every sentence adds value, and the narrative logically sequences the various actions. It is appropriately detailed for a tool with 14 actions, though it could be broken into sections for readability.

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 is highly complex (14 actions, 23 parameters, no output schema). The description thoroughly explains the main workflows (search/describe/invoke) and what they return (connect/checkout links, shareable prompt links). However, it does not detail the output of search, describe, list_tools, or other actions, nor error handling. It covers the essential use cases well but leaves some actions vague, making it incomplete for a fully self-sufficient 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?

With 0% schema description coverage, the description must compensate. It explains many key parameters: action (all enum values), mcp_id, tool_id, arguments, prompt fields (prompt_body, prompt_slug, prompt_title, prompt_vars, prompt_targets), and report_context. However, some parameters like limit, immediate, tier_slug, message, conversation, request_details, and cancel fields are not explicitly described, leaving a gap for less central 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 explicitly states 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It clearly identifies the resource (marketplace) and the actions it supports, differentiating it from siblings like authenticate or report_bug. It outlines the core flow (search → describe → invoke) and the prompt library aspect, 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 when-to-use guidance: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT in the active toolkit.' It also details when to use list_tools, subscribe/cancel, and the prompt library actions. It explains the auth/checkout flow and warns that writes require workspace owner/admin, giving clear context and 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, and the description adds meaningful extra context: no platform credentials are needed, each query is paid with prepaid credit, the data is official and not confidential, and the client is the LGPD controller. This goes beyond the structured 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 front-loaded with the tool's purpose and then adds concise operational, legal, and data-governance context. Each sentence contributes meaningful information, though the LGPD sentence is somewhat verbose for an MCP tool description.

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?

There is no output schema and no parameter documentation, so the description should at least indicate what the consultation returns and what inputs are required. It provides good legal/cost framing but leaves core invocation semantics underspecified.

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 does not explain the meaning, format, or required status of cpf, birthdate, or year. Since three parameters exist and two are required, the description should compensate for the missing schema descriptions, but it does not mention any of them.

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 states the tool performs 'consulta' of 'IRPF' from the 'Receita Federal' using official sources, giving a specific verb and resource. It does not explicitly describe the exact result returned, but it is clearly differentiated from the unrelated sibling 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 clear operational context: it is hosted by the platform, requires no platform credentials, costs prepaid credit per query, and returns only non-confidential official data. It does not explicitly name alternatives or exclusions, but the context is sufficient because the sibling tools are unrelated.

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 write behavior (readOnlyHint=false) and non-destructiveness, but the description adds little context about what happens after reporting or whether authentication is needed. It also mislabels the 'conversation' parameter as an array when the schema declares it as a string, creating confusion about the expected input format.

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 with no redundant words, front-loading the core purpose. It earns its length by adding the key reproduction detail.

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 output schema and sparse parameter descriptions, the description should cover required inputs and outcomes. It omits the purpose of the required 'message' parameter, doesn't explain the 'context' parameter, and gives no indication of what response the agent should expect after reporting.

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 0% description coverage, so the description must explain the parameters. It only refers to the 'conversation array' for reproduction but doesn't name the parameter or clarify its format, and it ignores both 'message' (the only required parameter) and 'context', leaving their purposes ambiguous.

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 verb 'Report' and the resource ('a bug, missing feature, or send feedback'), making the tool's purpose unambiguous. It distinguishes itself from sibling tools like authenticate or show_version by specifying the reporting functionality.

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 clear context for when to use the tool—when there is a bug, missing feature, or feedback—and instructs to include conversation data for reproduction. It does not explicitly name alternative tools or exclusions, but the purpose is clear enough that this is the obvious choice for issue reporting.

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 tool's safety profile is well covered. The description adds no additional behavioral context beyond the bare statement of what it shows, such as whether versions are fetched live or cached, or whether authentication is required when invoked.

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, straightforward sentence that fully covers the tool's purpose without any filler or repetition. It is front-loaded with the verb and noun and wastes no 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 zero-parameter, read-only read-only version-inspection tool with accurate annotations, the description is complete. It clearly states what the output pertains to (MCP platform and adapter versions), and no output schema is needed for a simple version endpoint.

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 accepts zero parameters and the schema description coverage is 100%, which requires no further explanation. The description does not introduce parameter semantics because there are none; this is appropriate and earns the baseline of 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 a specific verb ('Show') and a specific resource ('current MCP platform and adapter versions'). This differentiates it from sibling tools like authenticate, connect, and receipt lookup, which serve distinctly different purposes.

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 usage context is implied: the tool should be used when checking the current platform and adapter versions. However, it does not explicitly state when to use it versus alternatives like toolkit_info, which could also provide environment information.

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 non-destructive. The description adds valuable context by specifying exactly what state is returned (MCPs, connections, accounts, catalog counts), which goes beyond the annotations and clarifies the tool's output scope.

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, concise sentence that front-loads the core purpose and lists key output elements without any fluff. Every phrase 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?

For a zero-parameter, read-only info tool with strong annotations and a clear description of return content, the description is complete. No output schema is present, but the description adequately covers the expected return values.

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 takes zero parameters, and the schema is empty. With no parameters to document, the baseline is 4. The description does not add parameter-specific info (none needed), so it fully satisfies the dimension.

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 current toolkit state, enumerating specific components (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from siblings like 'show_version' (which likely focuses on version) and aligns with the name '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?

The description provides clear context on what information is returned, making the tool's use case obvious (inspecting toolkit state). While it doesn't explicitly state when not to use it or name alternatives, the context is sufficient for a simple informational tool.

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