CVM (Valores Mobiliários)

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

The description discloses key behaviors such as the two authentication modes (permanent vs session-only) and the no-args behavior of returning a link. This adds context beyond the annotations and does not contradict the idempotentHint.

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 two-sentence description is dense yet concise, covering three authentication paths without redundant wording. It front-loads the purpose and organizes options with clear separators, earning every word.

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 moderate complexity and lack of output schema, the description covers the main flows (permanent config, session token, link retrieval). It could be more explicit about session duration or return format, but it is sufficiently complete for an agent to invoke 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?

With 0% schema description coverage, the description fully compensates by explaining the 'token' parameter as a JWT for session-only login and clarifying that calling with no args gets a link. This gives complete semantic context for the optional parameter.

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 as authenticating for MCP.AI with IDE agents, explaining the login flow and token options. It is specific about the resource and action, but does not explicitly distinguish from the sibling 'connect' tool.

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?

Explicit usage instructions are provided for permanent config-based login, session-only token paste, and calling with no args to get a link. This gives clear context for when to use each invocation style, though it does not mention alternative 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, idempotentHint, and destructiveHint. The description adds behavioral context about the conditional return values (authenticated:true with empty pending[] vs connect_url when credentials are missing), going beyond what annotations 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?

Two sentences, no filler, and the key behavior is front-loaded. Every sentence adds information.

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?

Despite lacking an output schema, the description fully covers the return behavior for both relevant states. The tool's simplicity means this is 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?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics since none exist.

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, and explains the two possible outputs (authenticated vs credentials missing). This distinguishes it from siblings like authenticate (which likely initiates auth) and show_version/toolkit_info (which return other metadata).

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 checking whether all providers are connected and for retrieving connection URLs. It does not explicitly exclude alternatives, but the context is clear enough for a simple status 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond that: it discloses payment per query, no credentials required, public-access data, and LGPD responsibilities for the client. This exceeds minimal annotation coverage, though it omits potential edge-case behavior or rate limits.

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 front-loaded with the core purpose in the first sentence, followed by payment, access, and legal context. Most sentences serve a distinct purpose, though the explanation of public access is slightly redundant ('ACESSO PÚBLICO' + 'não é dado privado nem sigiloso'). Overall, it remains efficient and readable.

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 three parameters and no output schema, so the description carries significant responsibility. It adequately covers the tool's function, payment model, and data sensitivity, but it does not describe the return format, behavior when a record is not found, or the 'completo' parameter. This leaves notable gaps for an agent deciding whether to invoke it and interpreting results.

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 description clarifies that CPF and CNPJ are the identifiers used for the query, which gives meaning to those two parameters. However, the 'completo' parameter is entirely unexplained, and there is no mention of the expected format or the odd requirement that both CPF and CNPJ are marked as required. Since schema coverage is 0%, the description only partially compensates.

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 CVM registration records for individuals or legal entities using CPF or CNPJ. The verb 'Consulta' plus the specific resource (CVM cadastro) and input identifiers leave no ambiguity about the tool's purpose, and it is distinct from the sibling tools.

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 about when to use the tool (consulting public CVM data), including practical details like being hosted, no credentials, and prepaid credit. However, it does not explicitly exclude alternative tools or state 'when not to use,' so it stops short of full usage 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?

The description goes beyond the annotations by disclosing that invoke runs a tool even when not installed, that install makes an MCP permanent, and that writes require workspace owner/admin. It also describes the connect/checkout link behaviors, which are important side effects not captured in the schema or 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?

Although the description is a long paragraph, it is front-loaded with the core purpose and every sentence adds necessary detail about flows, exclusions, or the prompt library. There is no filler, and the dense format suits the tool's many actions.

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 primary workflows, auth requirements, billing edge cases, and the prompt library's response behavior. However, it does not detail the exact output structures for search or list_tools, and some param combinations are left to interpretation, so it is not fully exhaustive.

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 has 23 parameters with zero description coverage, but the description explains the purpose of key ones like action, mcp_id, tool_id, and prompt_slug. Many parameters remain undefined (e.g., limit, query, arguments, immediate), so it only partially compensates for the lack of schema 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 opens with 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' clearly establishing its dual role. It then enumerates the core action flow (search → describe → invoke) and separate capability areas like the prompt library, distinguishing it from sibling tools such as report_bug by noting that sub-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?

The description gives direct guidance: 'Core flow: action=search discovers MCPs by intent → describe returns... → invoke RUNS that tool.' It also states, 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT,' providing clear when-to-use rules. It also explains fallback links for auth/payment, which helps the agent decide next steps.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description's burden is lower. It adds useful context by instructing to include the conversation array for reproduction, which hints at what data may be transmitted. However, it does not disclose any potential side effects or what happens after reporting, so it falls short of being richly 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 two sentences long, with the first sentence clearly stating the purpose and the second providing essential usage detail. No unnecessary words or repetition. It is front-loaded with the most critical information.

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 simplicity (3 parameters, no output schema), the description covers the primary purpose and the most important parameter (conversation). However, the context parameter remains unclear, and the conversation serialization is ambiguous, leaving some gaps for a fully self-contained description. It is still adequate for a basic reporting 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?

Schema description coverage is 0%, so the description must explain the parameters. It explicitly mentions the conversation array, and message is implicitly the report text, but the context parameter is completely unexplained. The conversation parameter's type is string, yet the description calls it an 'array,' which could confuse the agent about expected format. This gap in coverage warrants a low 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?

The description states exactly what the tool does: 'Report a bug, missing feature, or send feedback.' The verb 'report' is specific, and the objects (bug, missing feature, feedback) distinguish it from sibling tools like authenticate or marketplace, which have no reporting function.

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 implies when to use the tool: whenever there is a bug, missing feature, or feedback to report. It does not explicitly mention alternatives or exclusions, but given the sibling tools are unrelated, no such differentiation is necessary. Providing an explicit 'use this instead of X' would elevate this to 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds minimal behavioral context. It simply says 'show,' which adds little beyond the annotations. There is no mention of response format, potential side effects, or any additional behavioral nuances.

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, clear sentence that is front-loaded with the verb and key information. It contains no fluff and effectively communicates 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 simple no-parameter tool with strong safety annotations, the description is sufficiently complete. It specifies exactly what versions are shown (platform and adapter), which is adequate given the absence of 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 baseline is 4. The description correctly implies there is nothing to configure, and the schema confirms 100% coverage. No additional parameter explanation 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 uses the specific verb 'show' and identifies the resource as 'current MCP platform and adapter versions.' This clearly distinguishes it from sibling tools like authenticate or connect, which serve 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 checking version information, but provides no explicit when-to-use guidance or mention of alternatives. No exclusions are stated, but the context of sibling tools makes the primary use case fairly obvious.

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 indicate readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable context about the specific content of the state (installed MCPs, connection status, accounts, catalog tool counts), which goes beyond what annotations provide and helps the agent understand exactly what information is available.

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 is front-loaded with the main verb and purpose. Every clause adds specific detail about the returned state, with no filler or repetition. It is both concise and informative.

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, no output schema, and strong annotations, the description carries the full burden of explaining what the tool returns. It does so thoroughly by listing all four components of the toolkit state, making it complete for an agent to understand the tool's behavior and expected output.

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 for the description to add about parameter meaning. The baseline of 4 is appropriate because the description fully compensates by explaining the output, which is the only thing an agent needs to know.

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 names a precise resource ('current toolkit state'), then enumerates exactly what is included: installed MCPs, connection status, accounts, and catalog tool counts. This fully distinguishes it from siblings like show_version, which is about version rather than the full state.

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 states what the tool returns, making it obvious that it should be used when a user needs an overview of the toolkit's MCP connections and accounts. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to select it appropriately.

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