Simples Nacional

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

The description adds context beyond annotations: it explains the difference between permanent (non-expiring) and session-only login, and that calling with no args yields a link. Annotations indicate idempotentHint=true, and the description aligns with that. It also targets IDE agents, which is extra 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 two sentences with dense information, but it's somewhat run-on and mixes user instructions with agent instructions. Still, every clause adds useful detail and there is minimal waste.

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, but the description covers the main behaviors: permanent vs session, no-args behavior, and token format. No output schema exists, but the description gives enough context 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 schema only has an optional token string with no description. The description clarifies the token is a JWT and explains concrete usage patterns: call with { token: '<jwt>' } or with no args to get a link. This significantly adds meaning beyond the 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 explains the tool's function: handling authentication by either generating a login link or accepting a JWT token for session login. It distinguishes from sibling tools by focusing on the auth flow for MCP.AI and IDE agents.

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 provides explicit guidance on two modes: permanent configuration via server header vs session-only token, and recommends the permanent approach as 'Best'. It also tells when to call with no args vs with token, offering clear usage context, though it does not explicitly list exclusions or 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?

Beyond the readOnly and idempotent hints, the description discloses the exact response behavior: authenticated:true with empty pending[] when connected, and connect_url plus per-install URLs when credentials are missing. This gives precise expectations without any contradiction with 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 two sentences, front-loaded with the main purpose, and every clause adds meaningful detail about return values. No unnecessary information is present.

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 status tool without an output schema, the description is complete. It explains both possible outcomes and what URLs are returned, leaving no significant ambiguity about the tool's behavior.

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 adds no parameter semantics because none are needed; it correctly focuses on output behavior.

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 return values for different connection states. It distinguishes this from sibling tools like 'authenticate' by its read-only status-check purpose.

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 when the tool is useful: to check whether all providers are connected or to retrieve connection URLs when credentials are missing. It does not explicitly name alternative tools, but the conditional behavior implies its role as a status-checking tool.

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 by disclosing that invoke runs uninstalled MCPs one-off, returns connect/checkout links on auth/billing obstacles, writes require owner/admin, and there is a one-off install behind invoke. This is rich operational context not conveyed by readOnly/destructive flags.

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 dense and each sentence adds valuable information, but it is a single long paragraph that is hard to scan. It could benefit from structural grouping (e.g., core flow, actions, prompt library, permissions). The length is justified by the tool's complexity, but formatting reduces 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 description covers core flows, special cases (credentials, billing), permissions, and output behaviors (connect link, checkout link, shareable prompt link). Missing items include the 'resume' action and full parameter semantics, but for a tool this complex it is quite complete. Minor gaps prevent 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 23 parameters and 0% schema description coverage, the description compensates by explaining key parameters conceptually (action, tool_id, arguments, prompt_vars, mcp_id) and the role of several fields through action descriptions. However, many parameters (immediate, resume, conversation, prompt_targets, etc.) remain unexplained, so it is strong but not exhaustive.

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 and execution engine, with a specific core flow: search → describe → invoke. It explicitly names its actions and distinguishes itself from siblings by explaining what report_bug, list_tools, request_mcp, and the prompt library do.

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 when-to-use guidance: use invoke for one-off execution, install for permanent toolkit addition, subscribe/cancel for billing, request_mcp when nothing fits. It names alternatives and special conditions (connect link for credentials, checkout link for payment, owner/admin requirement 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 indicate non-read-only, idempotent, and non-destructive behavior. The description adds context that the conversation array aids reproduction, but doesn't explain underlying effects, network behavior, or what happens after submission. No contradiction with 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 two sentences, front-loading the purpose and then adding a single actionable instruction. Every word earns its place with no redundancy or 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?

The description doesn't address output, return behavior, or post-submission effects. It also fails to clarify the type mismatch for the conversation parameter (described as array but schema says string). For a simple bug report tool it's adequate, but gaps remain regarding parameter format and outcomes.

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 partially by explaining that the conversation parameter should contain recent messages for reproduction. However, it leaves 'message' and 'context' undefined, relying on their names for meaning. The conversation parameter is described as an array while the schema specifies a string, creating a semantic mismatch.

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: to report a bug, missing feature, or send feedback. This specific verb+resource combination distinguishes it from siblings like authenticate and connect, 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 implies usage for bug reporting and instructs to include the conversation array, but does not explicitly state when to use this tool over alternatives or provide exclusions. It gives minimal contextual guidance beyond the basic purpose.

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=false, so the safe, read-only nature is covered. The description adds the specific output context (platform and adapter versions), which is useful behavioral information beyond the 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, front-loaded sentence with no wasted words. It gets straight to the point and fully captures the tool's function.

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 trivial complexity (no parameters, no output schema), the description is complete. It states what the tool returns (version information) and the annotations cover side effects. No additional context is necessary.

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 adds nothing about parameters because there are none to describe, and the schema is fully consistent with that.

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 ('Show') and identifies the exact resource ('current MCP platform and adapter versions'). This is clear and distinct from sibling tools, none of which target version information.

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—call this to check versions—but provides no explicit when-to-use/when-not-to-use guidance or mention of alternatives like toolkit_info. For a simple no-argument tool, implied usage is acceptable but not explicitly stated.

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 annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is known to be safe. The description adds context about authentication (none), prepaid pricing, and LGPD compliance, which are not in annotations. No contradiction found.

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, front-loading the main purpose. It includes necessary usage and compliance details without excessive fluff, though the LGPD sentence is somewhat extra but still 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 tool is simple with only 2 parameters and no output schema, yet the description omits explanation of the 'completo' parameter and the return format. It covers payment, auth, and data type, but gaps remain.

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 only implicitly references the CNPJ parameter ('a partir do CNPJ'). The 'completo' boolean parameter is not explained at all, leaving the agent to guess its purpose.

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 consults a company's Simples Nacional status from CNPJ, including option and enquadramento. This specifies a concrete action and resource, and the sibling tools (authenticate, connect, etc.) are unrelated, so there's no confusion.

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 provides context for when to use: hosted platform, no credentials required, pay per consultation with prepaid credit, and public access data. However, it does not explicitly mention alternatives or when not to use, though none of the sibling tools are direct 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by detailing the response contents (installed MCPs, connection status, accounts, tool counts), giving the agent a clear picture of what information the call yields.

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, well-structured sentence that front-loads the core action ('Returns the current toolkit state') and then compactly lists the main data categories. Every clause adds useful information without redundancy.

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 no-parameter, read-only tool, the description fully covers the tool's purpose and the shape of its return data. It lists four specific aspects of the state, making the output expectations clear even without an output schema.

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 is trivially complete. The description need not explain parameter semantics, and with 100% schema coverage, the baseline of 4 is appropriate.

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' with the resource 'current toolkit state' and enumerates the exact contents (installed MCPs, connection status, connected accounts, catalog tool counts). This clearly distinguishes it from sibling tools like authenticate or connect, which are action-oriented.

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 a clear use case: when you need to inspect the current toolkit state. However, it does not explicitly state when not to use this tool or mention alternatives (e.g., show_version for version information), so it stops short of a 5.

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