Portal da Transparência: Cadastro Nacional de Empresas Punidas (CNEP)

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

The description discloses that calling with no args returns a login link, and that passing a token enables session-only login. It also mentions the permanence of the config-based approach. Annotations include idempotentHint=true, which aligns with the description (calling with no args repeatedly just returns a link). No contradiction. However, it doesn't explicitly state that the token will be stored or how long the session lasts, but it covers key behavioral points.

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 sentence, but it's somewhat long and packed with information. It is front-loaded with the purpose, and then explains best practices and call patterns. It could be split into clearer parts, but it is concise and every part adds value. No waste, but structure could be improved 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 fairly simple (1 optional param), has annotations (idempotentHint), and the description covers the main user flows: permanent config vs session-only, and how to call. It doesn't need to explain return values (no output schema). The description is complete for an authentication tool, providing all necessary context for an agent to guide the user.

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 1 parameter 'token' with no description (0% coverage). The description explains the token parameter's usage (paste JWT) and the alternative no-arg call, thus adding meaning beyond the schema. However, it doesn't provide detailed format constraints beyond '<jwt>', which is sufficient. Baseline is 3 because the description compensates for the lack of schema description, but not deeply.

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: to authenticate the user for MCP.AI by either providing a login link or accepting a token. It specifies the resource ('MCP.AI for IDE agents') and the action ('log in', 'copy the access token'), and it distinguishes from siblings like 'connect' by focusing on authentication with explicit login flow.

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 usage guidance: it says 'Best' to add the token to the server config for a permanent connection, or paste it for a session-only login, and explains both call patterns: with { token: "<jwt>" } or with no args to get the link. It implicitly distinguishes from 'connect' by describing the login process, which is a clear alternative for establishing a connection.

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 valuable behavioral context: authenticated:true, empty pending[], connect_url, and per-install URLs. 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 two sentences, front-loads the core purpose, and packs conditional behavior into clear, concise language. Every sentence adds value with 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 zero-parameter, read-only status tool, the description covers the key scenarios, return values, and behavior, making it sufficiently complete even without an output schema. It is well-aligned with 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?

With zero parameters, the description has no burden to explain parameter semantics. The baseline of 4 applies, and the description does not need to add further detail.

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' and clearly identifies the resource as 'connection status and URLs'. It describes conditional outcomes, distinguishing it from sibling tools like authenticate. This is a clear, specific purpose statement.

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 by explaining what happens in two distinct scenarios: when all providers are connected versus when credentials are missing. However, it does not explicitly mention alternative tools or when not to use it, so it falls 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.

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

The description discloses key behaviors beyond the annotations: invoke runs one-off without installing, missing credentials return a connect link, empty wallet returns a checkout link, writes require workspace owner/admin, and search/describe flag installed_in_toolkit vs installed_in_workspace. Annotations only provide generic hints, so the description adds substantial behavioral context. 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 a single dense paragraph with many compound sentences and clauses, making it hard to scan. It front-loads the core flow but would benefit from bulleted sections for actions, permissions, billing behavior, and the prompt library. Although every sentence adds information, the lack of structure and sheer length prevent it from being 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?

For a tool with 23 parameters, 14 actions, and no output schema, the description covers an impressive amount of context: the search/describe/invoke flow, one-off execution semantics, auth and billing link behavior, permission requirements, installed flags, and the separate prompt library. It lacks parameter-level detail and return-shape information, but given the tool's breadth, it is largely complete.

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 compensates for many core parameters: action values, mcp_id, tool_id, arguments as a JSON string, and several prompt-related params like prompt_slug, prompt_vars, and prompt_body. However, many parameters remain unexplained, including limit, immediate, conversation, tier_slug, prompt_targets, cancel_reason, cancel_comment, report_context, request_name, and request_details. The agent would still need to guess formats and meanings for a large portion of 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 identifies marketplace as the official mcp.ai catalog and execution layer, with a concrete core flow (search → describe → invoke) and distinct sub-actions. It is broad because it is a multi-action dispatcher, but it differentiates internal functions like install vs invoke vs list_tools. It does not explicitly contrast with sibling tools, so it stops short of a 5.

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: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT'. It also explains when to use search, describe, list_tools, subscribe/cancel, report_bug, and request_mcp, and describes the retry flow after connect/checkout links. This is strong, actionable selection 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the source being official, non-confidential data, and clarifies that the client is the data controller under LGPD. This goes beyond annotations by addressing legal responsibility and data nature, which is valuable for an AI 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 paragraph, moderately concise, but packs much information: source, hosting, payment, data nature, and legal responsibility. It front-loads purpose, though the legal disclaimer might be slightly verbose for a tool description. Overall, sentences earn their 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?

The description covers the source, official nature, and legal context, but lacks details on expected output or result format (since no output schema), any constraints like rate limits or pagination, and does not sufficiently clarify parameter usage. For a simple query tool, it is somewhat complete, but with two undocumented parameters and no output schema, it leaves gaps.

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 two parameters (cpf and cnpj) beyond their names. It does not state that these are identifiers to query, which parameters are required (though schema shows none are required), or how they relate to each other. The description adds minimal value because it doesn't clarify the parameter semantics.

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 the CNEP (Cadastro Nacional de Empresas Punidas) via the Transparency Portal, an official Brazilian source. It distinguishes itself from siblings by describing the specific data source and purpose, though it could more explicitly contrast with sibling tools like marketplace 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?

The description implies usage context (querying official Brazilian penalties data) and mentions payment via prepaid credit, but it does not explicitly state when to use this tool versus alternatives. It lacks guidance on prerequisites like authentication or when not to use it (e.g., if no CNPJ/CPF is needed).

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 idempotentHint=true and destructiveHint=false, so the safety profile is known. The description adds the behavioral requirement to include the conversation array for reproduction, which is useful, but it doesn't elaborate on response behavior or side effects. This is adequate 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?

The description is a single, front-loaded sentence that clearly states the purpose and includes one key usage detail. Every word earns its place with no 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?

The tool is relatively simple, and annotations provide safety hints. However, the lack of explanation for the required 'message' parameter and no mention of response format or post-submission behavior make it slightly incomplete. The reproduction context is clear, but the required input remains ambiguous.

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 (for reproduction) but fails to explain the required 'message' or the optional 'context' parameter. This is a significant gap for the required field, leaving the agent uncertain about what to provide.

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: reporting bugs, missing features, or feedback. It uses a specific verb (Report) and resource (bug/feature/feedback), which distinguishes it from sibling tools focused on authentication, marketplace, and system 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?

It provides clear context for when to use the tool (reporting bugs/feedback) and even specifies what to include (the conversation array). However, it doesn't explicitly name alternatives or exclusion conditions, so it falls 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.

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered there. The description adds the output's scope ('current MCP platform and adapter versions') but does not disclose any additional behavioral details such as whether a network request is made or whether results may be cached. This is adequate but not deeply transparent.

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: 'Show the current MCP platform and adapter versions.' It contains no filler, redundancy, or irrelevant details, and every word contributes to understanding the tool's purpose.

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 side-effect-free, parameterless version query, this description is complete. There is no output schema, but the description tells the user what information the tool provides: current MCP platform and adapter versions. No additional prerequisites, configuration, or behavioral nuance is needed.

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 there is no parameter ambiguity for the description to resolve. The baseline for a zero-parameter tool is 4, and the description correctly focuses on what the tool returns rather than nonexistent 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 uses a specific verb ('show') with the resource ('current MCP platform and adapter versions'), making the tool's purpose immediately obvious. It also naturally distinguishes this tool from sibling tools like authenticate, connect, and portal_transparencia_cnep_consultar, which clearly have 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 the tool should be used when the user wants to know MCP platform or adapter versions, but it does not explicitly state when to use it instead of any alternative. No exclusions or alternative tool references are provided. For a simple version-query tool this is acceptable but not fully explicit.

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 destructiveHint=falseional; the description adds specific return contents (installed MCPs, account connections, catalog tool counts), which clarifies the tool's output beyond the annotations. No contradictions.

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, well-structured sentence that front-loads the purpose ('Returns the current toolkit state') and then lists specific contents with commas. No unnecessary 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?

Given the low complexity (no parameters, simple read-only info), the description is adequate. It specifies the main output fields. It doesn't mention whether results are returned in any specific format, but this is not critical for a status query. Slight gap in not mentioning how to interpret the state or whether the state is cached.

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?

Tool has 0 parameters, and the schema has no properties, so baseline is 4. The description doesn't need to explain parameters, and none are mentioned, which 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 clearly states the tool's purpose: it returns current toolkit state (installed MCPs, connections, accounts, catalog counts). This distinguishes it from action-oriented siblings like connect or authenticate, and from show_version which likely only shows version 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 implies usage context (state inspection) but does not explicitly state when not to use it or how it differs from alternatives like show_version. It gives clear context for its use case, earning a 4 rather than a lower score.

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