Viagens de Servidores (Transparência)

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

Annotations already declare idempotentHint true and destructiveHint false. The description adds valuable behavioral context about the two modes (permanent vs session-only), explains token handling, and notes that calling with no args returns a link. This goes beyond the 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?

Three sentences convey all necessary information without fluff. The opening phrase 'MCP.AI for IDE agents (Cursor, etc.)' adds minor context but is slightly extraneous. Overall, it is well-structured and front-loaded with the core action.

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 no output schema, the description tells users to expect a link when called with no args and explains the token submission flow. It could mention the response format for token acceptance or error cases, but it is sufficiently complete for a straightforward auth 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 a single optional token string with no description. The description explains that the token is a JWT pasted by the user, and that omitting it triggers the login link workflow. This provides essential semantic meaning that the schema lacks.

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?

Description clearly states the tool's function: authenticating MCP.AI for IDE agents by logging in via browser, obtaining an access token, and establishing either a permanent or session-only connection. Uses specific verbs like 'log in', 'copy', 'add', and 'paste', and distinguishes from siblings by focusing on the authentication 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?

Provides explicit usage instructions: recommends adding the token to server config for permanent connection, or pasting it for session-only login, and explains how to call without args to get the login link. This gives clear when-to-use and how-to-use 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 annotations by detailing exact response behaviors for both connected and missing-credential cases. It explains the return format (authenticated, pending[], connect_url, per-install URLs) which is valuable context not present in 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?

Two sentences, front-loaded with the action, and every sentence adds value. No fluff or redundant phrasing.

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 read-only tool, the description fully explains expected outputs in different states. Combined with rich annotations (readOnly, idempotent, non-destructive), nothing critical is missing.

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?

There are zero parameters, so the baseline is 4. The description appropriately says nothing about parameters since none exist, and the schema is empty. No additional parameter guidance 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 clearly states 'Returns connection status and URLs' - a specific verb and resource. It distinguishes from the sibling 'authenticate' tool by describing a read-only status check rather than an 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 provides clear context: it returns status and URLs under two conditions, implying it's for checking connectivity. It does not explicitly exclude alternatives like 'authenticate', but the contrast is reasonably clear from the description's emphasis on status.

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), the description discloses critical behaviors: invoke works even when the MCP is not installed and does not bloat the tool list, install makes tools natively available, write operations require workspace owner/admin, and invoke returns connect/checkout links when credentials or payment are needed. These details are essential for an agent to predict tool behavior safely.

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 dense and front-loads the main purpose, then uses arrows to map the core flow. It is longer than necessary and could be structured with lists or headings, but every sentence contributes meaningful information. Minor redundancies exist (e.g., repeating 'invoke works even when the MCP is NOT installed').

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 complex tool with 14 actions and no output schema, the description covers most critical aspects: billing, auth, permissions, prompt library, and the distinction between one-off and permanent installs. However, it omits the 'resume' action entirely and does not specify return formats for search/describe results, which could be important for an agent to parse the response.

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 well for the key parameters: it explains the action enum (search, describe, install, invoke, etc.), mcp_id/tool_id/arguments, and prompt-related parameters (prompt_body, prompt_vars, prompt_slug). However, many parameters like limit, query, immediate, cancel_reason, and conversation are left implicit or undescribed, leaving gaps for a 23-parameter tool.

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 opening sentence clearly states the tool's role: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' This is a specific verb-resource combination that distinguishes it from sibling tools like authenticate or show_version. It also explicitly covers capability requests and prompt library functionality, leaving no ambiguity about scope.

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 when-to-use guidance: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT in the active toolkit.' It also outlines the core flow (search → describe → invoke) and handles edge cases with connect/checkout links and retry instructions. This surpasses what annotations or schema alone offer.

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. The description adds context about needing the conversation array for reproduction, which is useful. But it doesn't disclose what happens after reporting (e.g., whether a copy is stored, if duplicate reports are possible). With annotations covering the safety profile, this is a 3.

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: the first front-loads the purpose, the second gives the critical instruction. No wasted words, every sentence earns its 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?

For a simple bug-report tool, the description is adequate but has gaps: one parameter ('context') is undocumented, and with no output schema it doesn't describe expected confirmation behavior. The reproduction guidance is valuable, but missing parameter semantics and return behavior pull it to a 3.

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 for all parameters. It explains the 'conversation' parameter (include recent messages) and implicitly 'message' (the report content), but 'context' is left completely undefined. For a 3-param tool, this is insufficient compensation.

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.' The verb 'report' is specific and the resource (bug/feature/feedback) is explicit. It distinguishes itself from sibling tools, which are about authentication, marketplace, version, and travel 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 instruction to 'Include the conversation array with recent messages for reproduction' gives clear context on how to use the tool effectively. It implies when to use it (when reporting a bug/feature/feedback) and no sibling tool overlaps, so exclusions are unnecessary. However, it doesn't explicitly state when not to use it.

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 provide readOnlyHint, idempotentHint, and destructiveHint=False. The description adds the specific resource being shown but no additional behavioral details such as output format or side effects. It is consistent with 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 sentence, front-loaded with the action, and contains 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?

This is a zero-parameter, read-only, idempotent tool without an output schema. The one-sentence description adequately conveys the tool's purpose and return value (version information). No further context 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 accepts no parameters, so the schema fully describes the input. The description does not need to add parameter information; baseline 4 applies.

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 clearly identifies the resource ('current MCP platform and adapter versions'), making it distinct from sibling tools like authenticate or marketplace.

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 does not explicitly state when to use this tool or contrast it with alternatives. However, for a simple version-retrieval tool, usage is implied whenever version information 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds value by disclosing exactly what state information is returned (installed MCPs, connection status, accounts, catalog tool counts), which is useful 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 a single, well-structured sentence that front-loads the main verb and resource, then lists specific components. Every word earns its place, with no redundancy or 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 simple tool with no input parameters and no output schema, the description adequately enumerates the return contents (installed MCPs, connection status, accounts, catalog tool counts). It provides sufficient information for an agent to know when to call it and what to expect.

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 has full coverage (no parameters to document). Baseline for 0 params is 4. The description focuses on return content, which is appropriate since there are no parameters to explain.

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 ('current toolkit state') with enumerated details (installed MCPs, connection status, accounts, catalog tool count). This distinguishes it from siblings like show_version or authenticate, which 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 usage for checking toolkit state but does not explicitly state when to use it versus alternatives or provide exclusion criteria. It's clear this is a status/read-only tool, but there's no direct comparison with 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: it is hosted on the platform, requires no credentials, is paid via prepaid credit, accesses only public official data, and notes LGPD compliance responsibility for the client. This is substantial additional transparency, though rate limits or pagination are not mentioned.

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 short paragraph, front-loaded with the core purpose in the first sentence. The subsequent sentences provide relevant operational and legal context without excessive wordiness. It is slightly dense but every sentence contributes value.

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 without an output schema, the description gives a good sense of the data scope and access model, but it omits return format details and fails to clarify the 'completo' parameter. It is adequate for orientation but leaves clear gaps for an agent preparing to invoke the 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 compensate for both parameters. It mentions CPF as the input ('a partir do CPF') but does not describe the expected format or the optional 'completo' boolean parameter at all. An agent cannot infer the meaning or effect of 'completo' from the description.

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 retrieves travel and expense data for federal executive branch public servants via CPF ('Viagens e despesas de um servidor do Poder Executivo Federal no Portal da Transparência a partir do CPF'). It names the specific resource, input, and scope, and is easily distinguished from generic sibling tools like authenticate, connect, and marketplace.

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 useful usage context (hosted on the platform, no credentials, paid per query, public data) but does not explicitly state when to prefer this tool over alternatives or when not to use it. The intended scenario is implied by the CPF-based query, but there are no exclusions or alternative tool references.

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