Receita Federal: Simples (DASN SIMEI)

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

Annotations already indicate idempotency and non-destructive nature. The description adds valuable context on the two authentication modes (permanent vs session-only) and the flow of getting a link or accepting a JWT. It does not mention side effects or token validation, but the core behavior is well disclosed.

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 longer than a one-liner but every sentence adds essential info. It is front-loaded with context and provides structured alternatives. Slightly informal phrasing and redundant 'log in in the browser' wording prevent a perfect score.

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 no output schema, the description covers the key inputs and behavior but does not explicitly state return values for the token-provided path. It is complete enough for an agent to understand how to initiate authentication and handle the two typical 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?

Schema has 0% description coverage, but the description fully compensates by explaining the 'token' parameter is a JWT that the user pastes, and that calling with no args returns a link. This gives complete meaning to otherwise bare schema.

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 authenticates for IDE agents, with specific flow: log in browser, copy token, and either add to config or paste. It distinguishes from sibling tools by focusing solely on authentication, making its 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?

Explicitly explains two usage modes: adding token to config for permanent connection (recommended) or pasting token for session-only login, plus no-args call to get link. This provides clear when-to-use guidance and even recommends the best practice, going beyond basic 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 readOnlyHint and idempotentHint, and the description adds valuable behavioral details beyond that: the specific fields returned ('authenticated:true', 'empty pending[]', 'connect_url', 'per-install URLs') and the conditions under which they appear. This enhances understanding 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?

Two crisp sentences. The first states the primary action and second details conditional outputs. Every word earns its place with no fluff.

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 parameter-less tool, the description covers the two most important states: fully connected and missing credentials. It doesn't detail partial connection states (e.g., some providers missing) but the 'empty pending[]' hint implies pending holds incomplete ones. Slightly more detail on trailing edge cases would make it complete, but it's adequate.

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 zero parameters, so the baseline of 4 applies. The description doesn't add parameter details (none needed) but compensates by describing the response structure, which is helpful given no output schema exists.

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' with specific behavior ('authenticated:true') and conditions ('When credentials are missing'). This is a specific verb+resource that clearly distinguishes it from siblings like 'authenticate' (which handle authentication actions) and '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 tool's purpose is obvious, but it doesn't explicitly say 'use when you need to check connection status' or contrast with alternatives like 'authenticate'. It does provide clear conditional contexts (all providers connected vs missing credentials), giving strong contextual guidance without naming alternatives.

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 annotations to explain behavioral nuances: invoke runs one-off without adding to toolkit, it returns connect/checkout links when auth or payment needed, and requires retry after user action. It also discloses that install makes MCP permanent, and that writes need owner/admin. No contradictions with annotations (readOnlyHint=false, openWorldHint=true, etc.).

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 with explicit signposts ('Core flow', 'KEY', 'Use install only') and front-loaded with the most important use cases. While it might be trimmed, every major concept earns its place given the tool's complexity. The longer length is justified by the need to cover multiple actions and edge cases.

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 23-parameter, multi-action tool with no output schema, this description is remarkably complete. It covers the primary search-describe-invoke flow, differentiated behavior for install vs invoke, auth and payment handling, ownership requirements, and the separate prompt library segment. It leaves little doubt about how to use the tool in most real scenarios.

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 core parameters (action, mcp_id, tool_id, arguments) through the flow description, and the prompt library actions (search_prompts, get_prompt, publish_prompt) are mentioned. However, many parameters like immediate, tier_slug, request_name, prompt_vars, cancel_reason etc. are not individually explained, leaving some ambiguity for a 23-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 explicitly identifies the tool as 'the official mcp.ai marketplace' and 'the way to run them', clearly stating its dual role as catalog and executor. It enumerates the full Python-like action list (search, describe, invoke, install, etc.) and distinguishes itself from sibling tools like authenticate and connect by describing the marketplace's unique capabilities (running uninstalled MCPs, prompt library).

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 decision rules: 'Core flow: action=search... invoke RUNS that tool', 'KEY: invoke works even when the MCP is NOT installed', 'Use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use'. It also names alternatives (list_tools, ssubscribe/cancel) and when to use them, plus prerequisites like owner/admin for writes. This is textbook

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 (readOnly, idempotent, non-destructive), the description adds valuable behavioral details: no platform credentials required, prepaid per-query cost, data is not confidential, and the client is LGPD data controller. This is meaningful operational and legal context that annotations alone do not provide.

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 reasonably concise and front-loaded with the main purpose. It covers cost, authentication, and legal responsibilities in a compact way, though there is slight redundancy between 'fonte oficial' and 'fontes e órgãos oficiais brasileiros'.

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 one-parameter lookup with good annotations and no output schema, the description covers the essential contextual factors: official source, non-confidentiality, cost model, and data-responsibility aspects. It does not detail the response format, but that is less critical for this 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?

The only parameter 'cnpj' has no schema description, and the description itself does not explain its format, expected value, or examples. The parameter name is somewhat self-explanatory in context, but the description provides no additional semantic value beyond the schema's variable name.

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 action ('consulta') on a specific resource ('Simples (DASN SIMEI)') from an official source ('Receita Federal'). It distinguishes itself from the unrelated sibling tools and makes the tool's function immediately obvious.

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 useful context: it is an official-source consultation, hosted by the platform, requiring no platform credentials, and paid per query. However, it does not explicitly state when to prefer this tool over alternatives, nor does it mention any exclusions or complementary 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?

Annotations already communicate idempotency and non-destructive behavior. The description adds that feedback is sent and that the conversation array aids reproduction, but it does not disclose recipients, data handling, or other side effects beyond what annotations imply.

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 compact sentences front-load the purpose and immediately follow with the key reproduction instruction. No filler or redundant wording.

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 reporting tool with annotations and no output schema, the description covers the essential purpose and the one non-obvious usage detail. It does not describe the conversation format or message parameter, but these are inferable from the schema and tool nature.

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 conversation parameter's purpose ('with recent messages for reproduction') but leaves the required 'message' parameter and optional 'context' parameter semantically unexplained.

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 verb and resource: 'Report a bug, missing feature, or send feedback.' This is specific and distinct from the unrelated sibling tools, making the purpose unmistakable.

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 on how to use the tool well: 'Include the conversation array with recent messages for reproduction.' It lacks explicit when-not-to-use guidance or alternatives, but the purpose statement itself prescribes the appropriate scenario.

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, destructiveHint=false, and idempotentHint=true, fully covering the safety profile. The description adds no further behavioral context but does not contradict the annotations, so a score of 3 is appropriate given the annotations carry the burden.

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 efficiently conveys the tool's function with no wasted words, perfectly front-loaded and 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?

For a simple read-only version-reporting tool with no output schema and no parameters, the description is fully adequate. It covers the essential purpose without needing additional context.

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% (no properties). With no parameters to document, the baseline of 4 applies, as the description need not elaborate on parameter meaning.

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 a specific verb ('Show') and a clear resource ('current MCP platform and adapter versions'), which clearly defines its purpose and distinguishes it from sibling tools like authenticate and connect that perform different actions.

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 or alternative guidance, the simple nature of the tool and its name make usage obvious. It is a trivial informational command, so explicit usage rules are unnecessary; the purpose itself implies appropriate 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context by specifying exactly what information is returned, which goes beyond the annotation-provided safety profile without contradicting it.

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 communicates the full purpose and return contents without any filler. Every element earns its place, and the structure is immediately scannable for an AI agent.

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?

With no parameters and no output schema, the description fully compensates by explicitly listing all returned dimensions. The explanation of toolkit state is complete for the tool's stated purpose.

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 imposes no burden. The description correctly focuses on the output rather than inputs, which is appropriate for a parameterless introspection 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 uses a specific verb ('Returns') and clearly identifies the resource ('current toolkit state'). It enumerates the exact contents of the return value — installed MCPs, connection status, accounts, and catalog tool counts — which differentiates it from sibling tools like show_version or 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 establishes that this tool is for inspecting toolkit state, which implies when it should be used. It does not explicitly mention alternatives or exclusions, but the stated scope is clear enough to guide selection among the listed sibling tools.

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