DER SP: Penalidades

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

Annotations indicate idempotentHint=true and destructiveHint=false, but the description goes beyond by explaining the two modes (permanent vs. session-only) and that the token is a JWT. It does not mention potential side effects like rate limits or auth requirements, but given the simple auth purpose, this is adequate. 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 compact and informative, with two sentences that cover all necessary points: purpose, steps, and alternatives. It is front-loaded with the tool's purpose and provides 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?

Given the tool is simple (one optional parameter, no output schema), the description covers the main usage scenarios. It could be more complete by mentioning what the output or success response looks like, but for an auth tool this is not critical. The description is sufficient for an agent to use 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?

Schema description coverage is 0%, so the description must carry the burden. It explains the token parameter as a JWT to be pasted for session-only login. It does not explicitly name the parameter in the description, but it clearly indicates its usage. This compensates for the schema's minimal 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 function: to authenticate the IDE agent with MCP.AI by either providing a token or obtaining a login link. It specifies the resource ('this server's config') and distinguishes between permanent and session-only login, which is distinct from sibling tools like 'connect' 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?

It provides explicit usage instructions: log in in the browser, copy the access token, and either add it to server config for permanent access or paste it as a token argument for session-only. It also explains when to call with no args to get the link. This is clear and actionable guidance beyond the schema.

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 description's role is to add context beyond those. It does so by explaining the return values (authenticated, pending, connect_url) under different conditions. This aligns with the annotations and adds useful operational details without contradicting any 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 exactly two sentences, with the primary action stated upfront ('Returns connection status and URLs') and the conditional behaviors explained succinctly. Every sentence earns its place, with no redundancy or 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?

With no output schema, the description must convey what the tool returns. It does so by describing the two main scenarios and the returned fields (authenticated, pending, connect_url, per-install URLs). While it doesn't define the full response structure or types, for a simple status-checking tool, this is adequate and covers the essential variations.

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 is 4 per the rubric. Since there are no parameters to document, the description doesn't need to add parameter-level detail, and the schema coverage is trivially 100%. The description adds no parameter information but doesn't need to.

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: 'Returns connection status and URLs.' This is specific (verb 'Returns' + resource) and distinguishes it from siblings like authenticate and marketplace by focusing on status. It also outlines behavioral outcomes for different states, 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 clear context on when results differ — 'When all providers are connected' vs 'When credentials are missing' — which implies when the tool is useful. However, it doesn't explicitly state when to prefer this over alternative tools, nor does it mention any exclusions. Still, the context is sufficient for an agent to infer its usage as a status checker.

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 readOnlyHint and idempotentHint annotations, the description adds important behavior: it is a paid query (pague por consulta), requires external credentials (sem credenciais da plataforma), and clarifies the data is not confidential and falls under LGPD responsibilities. This enriches the operational 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 reasonably concise and front-loaded with the purpose. Some content, such as the LGPD compliance sentence, is extra but still relevant for a legal context. Each sentence contributes to understanding the tool's nature and constraints.

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?

Even with annotations, the description does not explain how to use the parameters or what the output looks like. With five parameters and no output schema, the description leaves significant gaps that could prevent correct invocation, especially for an AI agent.

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 five parameters (renavam, login_cpf, login_senha, pkcs12_cert, pkcs12_pass). It only hints that platform credentials are not used, implying external login/PKCS12, but does not map these to specific schema fields or indicate which are 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 states the tool performs a query (consulta) for DER SP penalties from official sources. This clearly specifies the verb and resource, and it is distinct from the sibling tools which are platform utilities 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 context: it is an official source query, requires prepaid credit, and does not use platform credentials. However, it does not explicitly state when to use this tool over alternatives or when not to use it, though no similar query siblings exist.

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?

Despite annotations being sparse (readOnlyHint=false, openWorldHint=true), the description discloses critical behaviors: invoke runs one-off even without installation, missing credentials return a connect link, empty wallet returns a checkout link, and writes require workspace owner/admin. It also explains the difference between installed_in_toolkit and installed_in_workspace and that prompt links open without login. This goes well 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 long but dense and information-rich; every sentence adds meaningful behavioral or usage context. It is front-loaded with the tool's core identity and flow, then expands into key behavioral notes, permissions, and prompt-library sub-actions without repetition 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?

Given the tool's high complexity—14 actions, 23 parameters, no output schema, and minimal annotations—the description is remarkably complete. It covers discovery, execution, installation semantics, auth and payment edge cases, permissions, installed-status flags, and the separate prompt-library domain, leaving few unresolved gaps for an agent to act 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?

Schema description coverage is 0% for 23 parameters, and the description does not map most parameters to their relevant actions. While it does mention tool_id, prompt_vars-like variables, and prompt slug links, it leaves many params like immediate, tier_slug, arguments, cancel_comment, and request_details unexplained, so the agent must infer their meaning from names and defaults alone.

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 tool is the official mcp.ai marketplace catalog and execution gateway, covering discovery, inspection, one-off invocation, installation, billing, and prompt-library actions. It clearly differentiates itself from siblings by naming its unique scope and enumerating all 14 actions it supports.

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 usage guidance: the core flow is search → describe → invoke, with a clear rule to 'prefer invoke for a single/occasional use' and 'use install only to make an MCP PERMANENT.' It also explains when to use list_tools, subscribe/cancel, report_bug, request_mcp, and the prompt-library actions, effectively distinguishing among the tool's own sub-actions.

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 readOnlyHint=false and destructiveHint=false, so the tool performs an action but is not destructive. The description adds the guidance to include the conversation array for reproduction, which is a behavioral hint about inputs, but does not disclose side effects, persistence, or external communication. It does not contradict annotations, and as annotations are present but sparse, the description provides some added value but not rich 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 remarkably concise, using two short sentences with the purpose front-loaded. Every word adds value—the first sentence defines the purpose, and the second provides a key usage hint. There is no fluff or unnecessary 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 3 parameters, no output schema, and basic annotations, the description sufficiently covers the core purpose and the most important parameter (conversation). However, it omits any mention of the optional 'context' parameter and does not discuss potential side effects or return behavior, which is a minor gap. Given the simplicity, it is almost complete but not fully.

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 explicitly references the 'conversation' parameter by instructing to include the conversation array, and implicitly connects the 'message' parameter to the content of the bug report. However, it does not clarify the 'context' parameter, leaving it unexplained. This partial compensation merits a 3.

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: reporting a bug, missing feature, or feedback. It uses a specific verb ('Report') and identifies the resource (bug/missing feature/feedback), distinguishing it from sibling tools like authenticate 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 provides clear context on when to use the tool (when reporting issues or sending feedback) and even gives an instruction to include conversation history for reproduction. However, it does not explicitly state when not to use it or mention alternatives, though 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds the 'current' qualifier and version scope, but does not describe return format or edge cases; this is acceptable given the strong annotation coverage.

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 filler words. It front-loads the verb and object and every word 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?

For a zero-parameter, read-only version query with comprehensive annotations, the description is complete. It identifies the exact output subject and does not need to explain return values, as the result of showing a version is self-evident.

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 input schema is empty with full coverage, so the description has no parameter burden. The baseline of 4 applies because there is nothing for the description to clarify about 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 uses a specific verb ('Show') and names the exact resource ('current MCP platform and adapter versions'). This clearly communicates what the tool does and distinguishes it from sibling tools like toolkit_info, which imply broader toolkit 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 provides clear context: use this tool when version information is needed. It does not mention alternatives or exclusions, but for a simple version-query tool the intended usage is evident and unlikely to conflict with 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?

The annotations already establish that this is read-only, idempotent, and non-destructive. The description goes beyond annotations by disclosing the precise kinds of state information returned (connections, accounts, and catalog tool counts), which is useful behavioral context for the agent.

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 that lists all relevant output categories without filler. Every word contributes value, making it highly efficient.

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 that this is a simple parameterless info tool with strong read-only annotations, the description is sufficiently complete. It explains what the tool returns and the main components of that state, which is enough for an agent to decide whether to call it.

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 and there is no parameter-specific meaning for the description to add. The schema already fully covers the empty parameter set.

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 a clear resource ('current toolkit state'), then enumerates exactly what is included: installed MCPs, connection status, connected accounts, and catalog tool counts. This is specific enough to distinguish from the sibling tools, especially show_version.

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 use when an agent needs an overview of the toolkit's installed MCPs and their status, but it does not explicitly state when to prefer this over alternatives such as show_version. There is no exclusion or comparative guidance provided.

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