Receita Federal PJ

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

Discloses behavior beyond annotations: browser login flow, token handling, permanent vs session-only sessions, and the config header alternative. Consistent with idempotentHint=true and destroys nothing, while adding practical context about how authentication is achieved.

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, but the second is dense with multiple instructions. Every part adds value, and the main purpose is front-loaded. Slightly long but acceptable.

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 all invocation variants, parameter meaning, and background context for IDE agents. With one optional parameter and no output schema, the description is largely complete, though it does not explicitly describe the return format.

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?

Though the schema has zero description coverage, the description fully explains the single 'token' parameter: 'call with { token: "<jwt>" } after the user pastes, or with no args to get the link'. This completely compensates for the lack of schema-level documentation.

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 uses a specific verb and resource, making it distinguishable from sibling tools like 'connect'.

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 two explicit usage paths: adding the token to server config for a permanent connection, or pasting it via the 'token' parameter for a session-only login. Also explains calling with no args to get the link. Lacks explicit sibling comparison but gives strong contextual 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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context about output states (authenticated:true with empty pending[], and connect_url when missing credentials). However, it omits partial connection states where some providers are connected and others are not, leaving ambiguity in edge cases.

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 the first sentence stating the core purpose and the second providing conditional details. It is front-loaded, succinct, and every statement 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?

The tool is simple (no params, no output schema), but the description explains only two scenarios (all connected vs. credentials missing). It fails to cover partial connection states, which could be important for the agent to fully understand the response format. Given the absence of an output schema, this 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?

The input schema has zero parameters, so schema coverage is 100% and the baseline is 4. The description does not need to explain parameter meaning; it focuses on output behavior, which is appropriate for a no-parameter tool.

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 the tool 'Returns connection status and URLs', with a specific verb and resource. This distinguishes it from siblings like 'authenticate' which handles authentication itself. The purpose 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 behavior-based context (what happens when connected vs. credentials missing) which implies when to use the tool, but it does not explicitly state when to use this over alternatives or list any exclusions. No direct comparison to sibling tools is made.

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 discloses many behaviors beyond what annotations provide: invoke works for uninstalled MCPs, returns connect/checkout links for credential/payment gaps, requires admin for writes, and flags installed_in_toolkit vs installed_in_workspace. This is rich context not visible in the sparse 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 long, dense paragraph (400+ words) covering many sub-actions and context. It is front-loaded with the main purpose, but the structure could be improved with bullets or section breaks. Each sentence adds value, but the overall size is not concise.

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 is remarkably comprehensive for a complex tool with no output schema, covering the core flow, payment/auth fallbacks, permissions, and the prompt library. It does not explain every action (e.g., resume, immediate) or return values, but provides enough for most use cases.

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 coverage, the description compensates by explaining key parameters (action, mcp_id, tool_id, arguments) through the core flow. However, many parameters (limit, query, prompt_*, immediate, tier_slug) are not individually described, leaving gaps for less common actions.

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 the official mcp.ai marketplace, serving as both a catalog and execution layer for MCPs. It details the core flow (search → describe → invoke) and distinguishes itself from sibling tools like authenticate or 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?

Explicit guidance is given for when to use each action: search for discovery, describe for profiles, invoke for one-off execution, install for permanent additions, list_tools for currently callable tools. It also notes prerequisites like workspace owner/admin for writes and differentiates between MCP and prompt library usage.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable context: no authentication needed, pay-per-query billing, public data source, and LGPD compliance responsibility. It does not describe response format or error cases, but the safety profile is well covered 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 front-loaded with the core purpose and each sentence adds relevant context (payment model, public access, LGPD). It is reasonably concise, though the legal disclaimer could be slightly tightened without losing meaning.

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 having annotations for safety, the tool has 3 parameters with 0% schema coverage and no output schema. The description omits input formatting, the meaning of Qsa and 'completo', and any details about the response. It covers the access model and legal context but leaves essential invocation details unaddressed.

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 clarify parameters. It only explains CNPJ and vaguely mentions 'quadro societário' for Qsa, but does not explain Qsa's expected value format, why it is required, or what the optional 'completo' boolean does. This is insufficient for reliable 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 uses a specific verb ('Consulta') and a clear resource ('dados cadastrais de uma empresa na Receita Federal'), explicitly naming CNPJ as the key input and mentioning the optional 'quadro societário'. This makes the tool's purpose unambiguous and distinguishes it from unrelated sibling tools.

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 credentials, charges prepaid credits per query, and is limited to publicly accessible data. It does not explicitly name alternatives or exclusion cases, but no similar sibling tool exists, and the prerequisites for use are clear.

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 indicate this is idempotent and non-destructive, but the description adds no behavioral details beyond mentioning to include the conversation array for reproduction. It does not contradict annotations, but does not provide additional context such as expected outcome or side effects, which with annotations present 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?

Two concise sentences with no redundant information. The description is front-loaded with the purpose and followed by a practical instruction, making it highly scannable.

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 simple with no output schema and few parameters. The description covers the purpose, provides a key usage hint (conversation for reproduction), and is sufficient for an AI agent to select and invoke the tool. Minor gap: no mention of what constitutes a valid 'message' or any expected response, but these are not critical for a bug report 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 description coverage is 0%, so the description must compensate. It explains the purpose of the conversation parameter ('with recent messages for reproduction') but leaves message and context implicit. Since message is the required parameter and its meaning is fairly intuitive, this is minimally adequate.

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 specific verb 'Report' and clearly states the resource: 'a bug, missing feature, or send feedback'. This clearly distinguishes it from sibling tools like authenticate, connect, and show_version, which serve entirely 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 description explicitly states when to use the tool: to report a bug, missing feature, or send feedback. It does not explicitly mention not using it for other scenarios, but given the sibling context, the usage context is clear and unambiguous.

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 safety is covered. The description adds context by specifying that both 'platform' and 'adapter' versions are shown, which goes beyond the annotation details.

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 with no unnecessary words. It immediately conveys the tool's function and fits well with the minimal structure of a zero-parameter 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?

For a zero-parameter read-only tool with good annotations and no output schema, this description is completely sufficient. It states exactly what versions are shown, which is all an agent needs to know to select and 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 zero parameters, so the baseline is 4. The description does not need to explain parameters, but the phrase 'current MCP platform and adapter versions' clarifies the semantic scope of what the tool reports.

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 'Show' and the object 'current MCP platform and adapter versions,' clearly defining what the tool does. This distinguishes it from sibling tools like authenticate and marketplace, which have very 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 tool's purpose is self-evident and no alternatives are needed; it is the obvious choice for checking version info. Sibling tools are unrelated (authentication, connection, marketplace), so the context makes usage clear even without explicit 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=true and idempotentHint=true, covering the safety profile. The description adds valuable context about what specific state is returned (MCPs, connection statuses, accounts, tool counts), enriching the behavior beyond the annotations 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?

A single sentence that front-loads the core action and then compactly lists the key contents of the state. Every word earns its place; no filler.

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 informational tool with no parameters and no output schema, the description completely specifies what the agent can expect. Combined with the annotations, no critical information is missing.

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 parameter details. Baseline for zero-param tools is 4; the description appropriately explains what the tool returns, making parameter semantics non-applicable and fully covered.

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 specific verb ('Returns') and clearly identifies the resource ('current toolkit state') with a detailed enumeration of contents (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from sibling tools like show_version 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 clearly implies when to use this tool: whenever an agent needs to inspect the toolkit's current state, including installed MCPs and their connections. It does not explicitly exclude alternatives or state when not to use it, but for a stateless, read-only info tool this context is sufficient.

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