CVM: Processos Administrativos Sancionadores

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

The description goes beyond annotations by explaining the auth flow: it provides a link for browser login, accepts a token, and distinguishes persistent vs session-only behavior. While it doesn't explicitly mention idempotency, the idempotentHint annotation is consistent. It could have clarified side effects (e.g., storing token) a bit more, but overall it's 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 run-on paragraph with multiple instructions and examples, which could be better structured with bullet points or separate sentences. While all necessary information is present, it lacks brevity and clarity in presentation.

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 one optional parameter, no output schema, and a straightforward auth purpose, the description covers all necessary aspects: how to obtain credentials, how to pass them, and the two modes of operation. No further detail 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 input schema only defines 'token' as a string with no description, but the tool description fully explains its meaning: the JWT to paste for session login, with the alternative of omitting it to receive a link. This adds essential semantic value 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 states the tool authenticates the user for MCP.AI IDE agents, describing the browser login flow and token retrieval. It distinguishes from siblings like 'connect' and 'marketplace' by focusing on the auth-specific action.

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 explicitly tells when to use it (for logging in) and gives two concrete usage patterns: permanent via config header and session-only via token paste. It also mentions the alternative of calling with no args to get the link, effectively guiding when to call without parameters.

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=false, so the agent knows it's safe. The description adds concrete return behaviors (authenticated:true, empty pending[] when connected; connect_url and per-install URLs when missing), which is transparent about what the tool does in different states. It doesn't describe every possible field, but it's sufficient. Not a 5 because it doesn't mention any error handling or edge cases beyond missing credentials.

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, both information-dense. First sentence states the core purpose and key return fields. Second sentence explains the condition for missing credentials. No fluff, well-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?

The tool has no parameters, no output schema, and the description covers the two main operational states. For a read-only status tool, this is reasonably complete. However, it doesn't mention why one would use this tool (e.g., to check authentication status before other operations) or list the exact URLs returnedasi. The sibling tools like 'connect' and 'authenticate' exist, so a bit more context might be helpful, but given the simplicity, 4 is fair.

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 schema coverage is automatically 100% (there are no parameters to describe). The baseline for 0 params is 4, but here the description adds value by explaining the output conditions, which is more than just schema. Since there are no params, there's nothing to explain, so it gets a perfect score.

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?

Very clear: 'Returns connection status and URLs.' distinguishes the tool as a status/URL provider, and the detailed conditions (authenticated:true with empty pending[], or connect_url) remove ambiguity. It clearly differentiates from siblings like 'authenticate' which likely performs the actual authentication.

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 explains conditional behavior: when all providers are connected vs when credentials are missingtaslds. This implicitly tells the agent to use it to check overall status and obtain URLs for missing credentials. However, it doesn't explicitly state 'use this to check if authentication is needed' or contrast with the 'authenticate' sibling, so it falls short of being fully prescriptive.

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 safety profile is clear. The description adds valuable context: it's hosted by the platform, requires prepaid credit per query, and clarifies data is not confidential and the client is responsible for LGPD compliance. This goes beyond annotations by explaining the commercial and legal 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 a single paragraph with three sentences, each adding distinct value: purpose, commercial terms, and legal context. It's concise and front-loaded with the core purpose, though the legal disclaimer could be seen as slightly verbose for a tool description.

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 has 4 parameters, no output schema, and no parameter documentation, the description is incomplete. It explains the data source and legal context but doesn't clarify what the query returns, how to structure queries, or any limitations. The annotations cover safety, but the description lacks operational details for a tool with multiple optional parameters.

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 any of the four parameters (cpf, cnpj, nome, numero_processo). While the parameter names are self-explanatory, the description provides no guidance on which parameters are required, how they interact, or format expectations. With zero coverage, the description should compensate but doesn't.

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 queries CVM administrative sanctioning processes from an official source, which is a specific verb+resource combination. It distinguishes itself from siblings by focusing on CVM processes, though it doesn't explicitly name alternative tools for similar queries.

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 consulting official Brazilian sources and mentions payment via prepaid credits, but it doesn't explicitly state when to use this tool versus alternatives or provide exclusions. The context of official data and LGPD compliance gives some guidance, but it's not explicit about when-not-to-use.

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 sparse annotations (readOnly=false, openWorld=true), the description discloses rich behavioral facts: 'invoke works even when the MCP is NOT installed — it runs the tool pontualmente (one-off), without adding the MCP to the toolkit and without bloating the tool list.' It reveals the hidden one-off install behind invoke, auth/payment failure modes (connect link, checkout/top-up link with retry), permission requirements for writes (workspace owner/admin), and the shareable no-login link behavior for published prompts. Nothing contradicts 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 dense wall of text with no visual structure — no paragraph breaks, bullets, or headers — making it hard to scan for the action/parameter semantics it needs to convey. Every sentence carries meaning and the length is somewhat justified by the scope (14 actions, 23 params), but the lack of front-loading and structure significantly hurts parseability for an 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?

Given the very high complexity (14-action enum, 23 params, 0 required), no output schema, and no per-parameter descriptions, the description does heavy lifting: it covers the core search→describe→invoke flow end-to-end, install-vs-invoke tradeoffs, auth/payment edge cases, permissions, and the separate prompt library subsystem. Remaining gaps are on secondary parameters (cancel/request/prompt metadata fields) and exact return shapes, but the essential behaviors are well documented for a tool this broad.

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 full semantic load for 23 parameters — and it does substantial work: it explains the action enum's 14 values (search discovers, describe returns full profile, invoke runs with tool_id+arguments, etc.), the relationship between mcp_id/tool_id/arguments, and the prompt_* family. However, several parameters are only lightly or not explicitly covered (conversation, immediate, cancel_reason/cancel_comment, request_name/request_details, prompt_title/prompt_category/prompt_targets), leaving gaps given the 0% schema coverage.

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 mcp.ai marketplace — the catalog and execution engine for all MCPs, covering capability discovery, description, and invocation. It distinguishes itself from sibling tools (authenticate, connect, toolkit_info) by being the discover-and-run entry point rather than an auth or info utility. Verb+resource is specific: 'catalog of every MCP/tool' with a defined search→describe→invoke core 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 gives explicit when-to-use guidance: 'prefer invoke for a single/occasional use' and 'use install only to make an MCP PERMANENT in the active toolkit,' contrasting the two paths. It names alternatives explicitly (list_tools for what is callable now, subscribe/cancel for billing, request_mcp for new builds, search_prompts for the prompt library) and even handles the retry-after-payment edge case ('the user opens it, then you retry').

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 idempotentHint=true, meaning repeat calls have same effect, and destructiveHint=false, meaning non-destructive. The description aligns with this, as reporting a bug is a non-destructive, idempotent action. It adds context about including conversation array for reproduction, but doesn't disclose other behaviors like whether the report is anonymous, internal, or if there's a rate limit. With annotations providing a safety profile, the description adds some value but not extensive behavioral detail.

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 long, front-loaded with the purpose. It mentions the key inputs without fluff. It is concise and structured effectively, though it could add a bit more detail on parameters without bloating.

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, but with zero schema coverage, the description should fully explain each parameter. It explains 'conversation' but not 'context', and doesn't mention that 'conversation' should be a JSON string representation of an array (given the default '[]' as a string). Also, it doesn't specify whether the 'message' should include reproduction steps. Given its simplicity, a complete description would cover all parameters, so this is incomplete.

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. The description names 'conversation' and explains its purpose ('array with recent messages for reproduction'), and implies 'message' is the bug report text. It does not explain 'context' parameter at all. With three parameters and zero schema coverage, the description only partially compensates, leaving 'context' undefined and 'conversation' format unspecified (it says 'array' but schema says default '[]' as a string). This is a gap.

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: 'Report a bug, missing feature, or send feedback.' This matches the name 'report_bug' and broadens to feedback, which is appropriate. It distinguishes itself from siblings like 'show_version' or 'toolkit_info' by focusing on user-reported issues, not 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?

The description says to 'Include the conversation array with recent messages for reproduction,' which implies when to use it: when reporting an issue that needs reproduction context. However, it doesn't explicitly state when not to use it (e.g., for general questions or feature requests that don't need reproduction) or mention alternatives like 'connect' or 'marketplace' for other needs. It provides some practical guidance but lacks exclusion criteria.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which fully cover the tool's safety profile. The description adds no new behavioral context beyond what annotations already provide, but given the simple nature of a read-only version checker, this is acceptable. No 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?

The description is a single, succinct sentence with no wasted words. It is appropriately front-loaded and perfectly sized for a zero-parameter 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?

Given zero parameters, complete annotations, and a clear one-sentence description, the tool is well-specified. The only minor gap is the lack of a note on output format, but the description already highlights the content scope (platform and adapter versions).

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 there is nothing to document. The description's mention of 'MCP platform and adapter versions' clarifies the output granularity, which is helpful since there is no output 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 'Show the current MCP platform and adapter versions' clearly states the tool's purpose with a specific verb and resource. It is distinguishable from siblings like 'toolkit_info' which likely provides broader information, and no other sibling seems to focus on version display.

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 checking versions, which is clear given the tool's simplicity and the absence of complex context. However, there is no explicit guidance on when to use this tool over siblings like 'toolkit_info' or 'show_version' vs other informational 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is consistent with those. It adds useful context about what state is returned, but does not disclose edge cases like missing connections or sensitivity of account 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 concise sentence with a clear front-loaded verb and a concrete list of returned information. Every word contributes meaning, with no filler or 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?

This is a low-complexity tool with no parameters and no output schema. The description enumerates the main categories of returned state well enough for an agent to understand what the tool provides without further detail.

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 appropriately implies a no-input introspection call, and there are no schema fields needing clarification.

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 'current toolkit state' with concrete detail: installed MCPs, connection status, associated accounts, and catalog tool counts. This clearly differentiates it from sibling tools like connect, authenticate, and 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?

No explicit when-to-use or when-not-to-use guidance is provided, nor are alternatives named. The intended use as a general toolkit introspection tool is implied by the content, but it does not say when to prefer this over show_version or marketplace.

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