B3: Participantes

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

Annotations provide idempotentHint=true and destructiveHint=false; the description adds that calling with no args returns a link, with token sets a session, and config gives permanent access. This discloses side effects and behavior beyond annotations. It doesn't mention error cases, but it's transparent about the two modes.

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?

Three sentences, each with a purpose. Front-loaded with the login flow. No fluff. Very concise and 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?

Tool is authentication, one optional param, no output schema. Description explains two usage modes, what to do with token, and permanent vs session. It's complete enough for an IDE agent to understand how to invoke it. Does not describe response, but that's acceptable since no output schema. Score 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?

Only one optional parameter (token), schema coverage is 0% (schema only has type string, no description). The description compensates by explaining that token is a JWT from copying from browser, and that calling with no args gives a link. This adds meaning. Could explicitly state that token is required for session auth, but it's clear. Score 4.

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 with MCP.AI for IDE agents, providing a link or accepting a token. It specifies the verb 'authenticate' and the resource (MCP.AI server), and distinguishes between two usage modes. While it doesn't name sibling alternatives, the purpose is 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 explicitly provides usage options: add token to config for permanent access, or paste token for session-only, and explains when to call with token vs no args. It gives clear when-to-use guidance without mentioning alternatives, but alternatives are unrelated (connect, marketplace).

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 valuable context about payment (prepaid credit), legal responsibilities (LGPD), and data confidentiality (not confidential). No contradictions with annotations, and it provides relevant behavioral details beyond the structured fields.

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 relatively short but packs in legal and payment information that could be streamlined. It is not front-loaded with the most critical usage instructions; the first sentence covers purpose, but subsequent sentences mix operational and compliance details. It is adequate but could be more focused.

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 read-only tool with one parameter, the description covers key aspects: official source, payment model, credentials, LGPD responsibilities, and data sensitivity. Annotations handle safety guarantees. It does not describe return format, but without an output schema, this is acceptable for a straightforward query 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?

The schema has only one parameter (cnpj) with zero description coverage. The tool description does not explain the format, purpose, or constraints of the cnpj parameter, relying entirely on the schema's basic string type. It fails to compensate 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 clearly states it queries official Brazilian sources (B3 participants) and distinguishes from sibling tools like authenticate, connect, and marketplace. The combination of tool name and description ("consulta em fonte oficial", "Consulta informação de fontes e órgãos oficiais brasileiros") makes 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 usage context by noting it requires prepaid credit, involves no platform credentials, and that the client is responsible for LGPD compliance. However, it does not explicitly state when NOT to use this tool or contrast it directly with alternatives, leaving some room for interpretation.

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 agent knows this is a safe read operation. The description adds behavioral context about the two states (all connected vs. missing credentials) and what fields are returned (authenticated, pending, connect_url). It does not describe any side effects or additional behavior, but given the annotations, the description adds sufficient value.

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 primary purpose, and provides concrete details about the two states. Every sentence adds value, and there is no fluff or repetition.

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 no parameters, no output schema, and annotations cover the safety profile, the description is complete enough. It explains the two possible outcomes and what URLs are returned. It could mention the format of the URLs or the exact structure of the response, but for a simple status check, this is adequate.

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 schema description coverage is 100% (vacuously). The description does not need to explain parameters. The baseline for 0 params is 4, and the description appropriately focuses on the output semantics, which is the relevant information for the agent.

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 distinguishes between the all-connected state and missing-credentials state. It is specific about the resource (connection status) and the output (authenticated flag, pending array, connect URLs). It doesn't explicitly differentiate from siblings, but the purpose is clear.

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 when to use this tool: to check connection status and get URLs when credentials are missing. However, it does not explicitly state when not to use it or mention alternatives like 'authenticate' or 'toolkit_info'. The context is clear but lacks explicit guidance on choosing between this and 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, etc.), the description discloses important behavioral traits: invoke runs a tool one-off without installing it, writes require workspace owner/admin, credential needs return a connect link, and empty-wallet paid usage returns a checkout/top-up link. It also clarifies installed_in_toolkit vs installed_in_workspace flags. 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 long but dense, front-loading the core identity and flow before diving into edge cases like auth links and permissions. The run-on, paragraph-style structure makes it harder to parse mentally, but nearly every sentence earns its place given the tool's 14-action surface area. A bit of bullet formatting would improve it further.

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 very high complexity (14 actions, 23 params, no output schema), the description covers most important behaviors and return shapes: describe returns full profile, invoke returns connect/checkout links, publish_prompt returns a shareable slug link. It omits or under-specifies some actions (resume is never mentioned) and does not describe return formats for every action, but for a mega-tool this is a robust high-level map.

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 must compensate, and it partially does: it explains the core flow around action, mcp_id, tool_id, and arguments, and names some prompt-library parameters (prompt_slug, prompt_vars, prompt_body). However, many parameters such as limit, immediate, tier_slug, conversation, cancel_reason, report_context, request_name, and prompt_targets are never explained, leaving major gaps for an agent to infer.

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 catalog and runtime: 'search discovers MCPs by intent → describe returns one MCP's full profile → invoke RUNS that tool.' It enumerates the distinct action families (search, describe, invoke, install, billing, prompts). However, it does not explicitly contrast the tool with sibling tools like authenticate/connect/report_bug, and even includes a report_bug action that duplicates a sibling, slightly blurring boundary clarity.

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 routing guidance: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT in the active toolkit.' It also clarifies when to use request_mcp ('when nothing fits'), list_tools, subscribe/cancel, and the prompt-library actions, plus the auth/billing retry flow. This is strong, actionable when-to-use coverage.

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 false, idempotentHint true, and destructiveHint false, covering the main behavioral expectations. The description adds the reproduction instruction but does not disclose any additional side effects, return values, or error conditions. With annotations present, this is adequate but adds limited transparency beyond the structured fields.

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 concise sentences, front-loaded with the primary action followed by a specific usage requirement. No filler or redundant content.

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 tool with three parameters, no output schema, and strong annotations, the description covers the essential purpose and gives a concrete instruction for reproduction. It lacks details on return behavior or edge cases, but given the simplicity)Skiping, it is sufficiently 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?

Schema description coverage is 0%, so the description must compensate. It explicitly references the 'conversation' parameter for reproduction, adding functional meaning. However, 'context' is not explained, and the schema types are minimal. The description adds some value but leaves one parameter semantic undefined.

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: 'Report a bug, missing feature, or send feedback.' This is a specific verb+resource and unambiguously distinguishes it from sibling tools, which cover unrelated operations like authentication and marketplace 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 provides clear context on when to use the tool (for reporting bugs or feedback) and offers a practical instruction: 'Include the conversation array with recent messages for reproduction.' It does not explicitly exclude any scenarios or name alternative tools, but no alternatives exist among siblings, making the guidance clear.

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, which cover the safety profile. The description adds no additional behavioral context beyond implying a read operation, such as return format or side effects. It is consistent with annotations, so 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, front-loaded sentence with no unnecessary words. It conveys the essential information efficiently and is easy to parse.

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 trivial tool with no parameters and no output schema, the description fully covers what the agent needs to know. It clearly identifies the action and target, and the sibling list confirms its distinct role.

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 description does not need to explain any. The baseline for 0-param tools is 4, and the description adequately communicates the tool's purpose without needing parameter details.

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 a specific verb ('Show') and resource ('MCP platform and adapter versions'), clearly distinguishing it from sibling tools like authenticate, connect, and marketplace. No ambiguity remains about the tool's 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 implies usage through its purpose but does not explicitly state when to use it or when to prefer alternatives. No exclusions or context about when to invoke this tool versus others are provided, so guidance is only implied.

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 read-only and idempotent behavior; the description enhances this by detailing exactly what state is returned (MCPs, statuses, accounts, counts). It adds value beyond annotations by scoping the output content, though it does not discuss edge cases like connection failures or performance, which is acceptable for an info endpoint. 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, well-structured sentence that front-loads the primary action and then enumerates specific data points with a colon and commas. Every word contributes meaning, with no filler or redundancy—exemplary conciseness.

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?

As a parameterless, read-only informational tool with no output schema, the description fully covers what the agent needs to know: the exact categories of state returned. It is complete for its simplicity, and annotations cover safety (non-destructive, idempotent), so no further disclosure 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?

With zero parameters, the baseline is set to 4 per rubric. The description correctly avoids parameter details since none exist, and the schema is empty with 100% coverage. The description stands on its own to clarify the tool's operation, satisfying the baseline.

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 the current toolkit state' and enumerates specific components (installed MCPs, connection status, accounts, catalog tool counts), making its purpose unambiguous and distinct from siblings like show_version or authenticate. The verb 'Returns' and detailed scope provide a precise resource definition.

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 inspecting toolkit state but does not explicitly state when to use it over siblings or exclude alternatives. It provides clear context of the returned data but lacks explicit 'use this when' or 'instead of' guidance, so it stays at the level of implied usage rather than explicit direction.

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