Beneficiário Final

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

The description reveals behavior beyond annotations: two modes (permanent via config, session via token param) and the no-args behavior of returning a link. Annotations already note idempotence and non-destructiveness. It doesn't describe potential errors or return value details, but for an auth tool it's adequate.

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 but packs a lot of information. It's two sentences, but the second is long and contains multiple clauses. All content is relevant and earns its place, though a bulleted structure could improve 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?

Given the tool's simplicity (one optional param, no output schema), the description covers the necessary behavioral details: how to authenticate permanently and temporarily, and what happens with no args. It doesn't explicitly state the return format, but that's implied ('get the link'). Complete enough for an AI 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?

The schema has a single 'token' string with no description (0% coverage). The description compensates fully by explaining the token as a JWT and the no-arg case for getting the link. It gives clear semantics for when to include or omit the 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 defines the tool's purpose: authenticating IDE agents via browser login and token capture. It describes the specific resource (access token) and the flow. However, it doesn't explicitly contrast with sibling tools like 'connect', so it slightly misses explicit differentiation.

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 scenarios: adding token to config for permanent connection, or passing token for session-only login, or calling with no args to obtain the link. It tells the agent exactly when to use which invocation, which exceeds basic guidance. It doesn't mention alternative tools, but the instructions are highly actionable.

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 mark the tool as read-only, idempotent, and non-destructive. The description goes further, disclosing the payment model ('pague por consulta com crédito pré-pago'), the public nature of the data ('ACESSO PÚBLICO em bases e fontes oficiais'), and LGPD responsibilities. This is rich behavioral context 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 three sentences, moving from purpose to payment to legal context, with no redundancy. Every sentence adds value and avoids repeating schema or annotation 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?

The description covers the tool's purpose, use case, payment requirements, data source, and LGPD compliance. However, it does not describe the return format or explain the 'completo' parameter, and there is no output schema to fill that gap.

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 coverage is 0%, so the description must compensate. It clarifies that CNPJ refers to companies and CPF to individuals, but the phrase 'CNPJ ou CPF' contradicts the schema which requires both fields. Additionally, the 'completo' boolean parameter is not mentioned at all, leaving its meaning unexplained.

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: 'Identifica o beneficiário final de uma empresa ou pessoa a partir do CNPJ ou CPF, para diligência de compliance.' This specifies the verb, resource, inputs, and purpose, making it distinct from sibling platform tools (authenticate, connect, etc.) which are unrelated.

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 an explicit use case ('para diligência de compliance') and context about payment and credentials, but does not mention when not to use it or name alternative tools. Since there are no directly competing siblings, the guidance is adequate but not exhaustive.

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, covering the safety profile. The description adds value by detailing the response behavior in different states (all providers connected vs. credentials missing), including the 'pending[]' array and connect_url. No contradictions 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 just two sentences, front-loaded with the primary purpose. Every sentence contributes meaningful information without redundancy or padding, making it exceptionally 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?

The description covers two states (all connected and credentials missing) but does not explicitly address partial connection states or clarify the contents of the 'pending' array beyond being empty. Given there is no output schema, the description carries the burden of explaining return values, leaving some ambiguity.

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 schema coverage is trivially 100%. With no parameters to explain, the description need not add parameter semantics; the baseline of 4 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 uses the specific verb 'Returns' with resource 'connection status and URLs', and further elaborates on conditional outcomes (authenticated:true with empty pending[] vs. connect_url responses). This clearly distinguishes it from sibling tools like 'authenticate' and '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 the tool is for checking connection status and obtaining URLs when credentials are missing, which is useful contextual guidance. However, it does not explicitly state when to use this tool over alternatives or provide exclusions, so the usage guidance remains implied rather than 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 signal readOnlyHint=false, openWorldHint=true, etc., but the description adds critical context: invoke works even when the MCP is not installed, returns a connect link if credentials are needed, returns a checkout/top-up link if payment is required, and writes require workspace owner/admin. It also notes that search/describe flag installed_in_toolkit vs installed_in_workspace, all beyond the boolean 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 that covers many topics, making it hard to scan quickly. It repeats 'MCP' frequently and packs multiple clauses with 'and' and '→'. Every sentence carries information, but a bulleted or sectioned layout would significantly improve readability and agent parsing.

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 breadth (14 actions, 23 params, no output schema), the description covers the core search→describe→invoke flow, install vs invoke, auth/payment outcomes, admin requirements, and the prompt library. It stops short of specifying return shapes for every action (e.g., search results, list_tools format) or handling error cases, but it covers the primary usage patterns well.

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 by explaining the action enum values and the meaning of key parameters (query, mcp_id, tool_id, arguments, immediate). It also covers the prompt library parameters (search_prompts, get_prompt, publish_prompt, prompt_vars, etc.). However, some parameters (limit, cancel_reason, report_context, request_details) are only implicit via action names, so a slightly higher explicitness would be ideal.

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 a clear, specific statement: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It enumerates distinct actions (search, describe, invoke, install, list_tools, prompt operations) and explicitly covers the scope (MCPs and prompt library), which distinguishes it from sibling tools like authenticate or connect.

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 lays out the core flow: 'action=search discovers MCPs by intent → describe returns one MCP's full profile ... → invoke RUNS that tool.' It also provides explicit contrast: 'prefer invoke for a single/occasional use' versus 'Use install only to make an MCP PERMANENT.' It names when to use request_mcp, list_tools, and the prompt library actions, plus states the admin requirement for writes.

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 readOnly=false, destructive=false, and idempotent=true. The description adds the reproduction context but does not disclose side effects, auth requirements, or rate limits, offering only minimal behavioral transparency beyond 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?

A single concise sentence that front-loads the action and includes a specific, actionable instruction. 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 three-parameter tool with no output schema, the description covers the purpose and the key usage detail (conversation array). The unexplained context parameter is optional with a default, so overall completeness is good but not perfect.

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 references the conversation array and implies message holds the report content, but the context parameter remains unexplained. This partial coverage leaves a notable 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?

Clearly states the verb 'Report' and the objects 'bug, missing feature, or send feedback'. It is distinct from siblings like authenticate, marketplace, and show_version, which handle other concerns.

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?

Provides direct usage guidance by instructing to include the conversation array for reproduction. Sibling tools are clearly unrelated, so no exclusions are needed; the context is unambiguous.

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 established. The description adds 'current' to indicate a live status but does not disclose additional behavioral traits 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 a single, front-loaded sentence with no filler or redundancy, ideal for a simple version-retrieval 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?

The tool is trivial, has no parameters, and the annotations cover safety. The description sufficiently conveys what the agent needs to know to select and invoke it, given the 100% schema coverage and absence of 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 accepts zero parameters, so there is no parameter semantics to document. The baseline of 4 applies because no further compensation is 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 a specific verb ('Show') and specifies the resource ('current MCP platform and adapter versions'), making its function unambiguous. This distinguishes it from sibling tools like authenticate or marketplace, which focus on different concerns.

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 that this tool is for retrieving version information but does not provide explicit guidance on when to prefer it over alternatives. However, given its specialized purpose, the usage context is reasonably clear without needing exclusions.

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 does not contradict them. It adds context about what the returned state contains but does not disclose additional behaviors like rate limits, caching, or session-specific data.

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, front-loaded with the action ('Returns the current toolkit state') and then listing the included components in a readable list. There is no wordy 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 zero-parameter, read-only tool with no output schema, the description sufficiently covers what the agent will get: installed MCPs, connection status, connected accounts, and catalog tool counts. It does not specify the exact output format, but that is beyond the minimal requirement for such a simple 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 tool has zero parameters, so the description correctly avoids discussing any. With no schema details to elaborate, the absence of parameter documentation is perfectly appropriate, and the description adds clarity by stating what the tool returns.

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 specifies the resource ('current toolkit state') with detailed contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly distinguishes it from sibling tools like show_version or connect.

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 makes the usage context obvious: it is an overview/status tool for the whole toolkit. However, it does not explicitly state when to use it over alternatives such as show_version or connect, leaving some room for ambiguity in tool selection.

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