Portal da Transparência: Servidor Público

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

The description discloses that calling with no args returns a login link, that passing a token yields a session-only login, and that configuring the header gives a non-expiring connection. This goes beyond annotations (which only mark idempotent and not destructive) by explaining the two operational modes. 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 three sentences, front-loaded with context ('MCP.AI for IDE agents'), then presents the two authentication modes and the no-args behavior. Every sentence provides necessary guidance 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 one optional parameter and no output schema, the description explains the core workflow and the two ways to authenticate (permanent config vs. session token). It could add more detail about what happens after successful authentication (e.g., the response format), but it is substantially complete for practical use.

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 provides only the name 'token' with no description, so schema coverage is 0%. The description fully compensates by explaining that token is a JWT pasted by the user, and that omitting it (no args) returns the login link. This gives complete meaning to the single 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 is for logging in via browser and obtaining an access token for MCP.AI IDE agents. It describes the action ('log in', 'copy the access token') and resource (authentication for the server). However, it does not explicitly differentiate from the sibling tool 'connect', which may serve a similar purpose, so it stops short of a 5.

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 a token to the server config for a permanent connection, or pasting a token for session-only login, or calling with no args to get the login link. It gives clear 'best' versus 'or' guidance, but does not compare against sibling tools like 'connect', so there is no explicit '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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is known to be safe. The description adds valuable behavioral detail about the output in two scenarios (all connected vs. missing credentials), including specific fields like authenticated, pending[], and connect_url. This goes beyond structured metadata, though it could mention edge cases like partial connectivity.

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, tightly written, and front-loaded with the primary purpose. No wasted 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?

With no output schema slash parameters, the description explains the two primary behavioral states (all connected vs. missing credentials) and what the return structure looks like. It adequately covers the tool's behavior for a simple status check.

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 no parameters, so baseline is 4. The description doesn't need to explain any parameters, and it doesn't. It adds value by explaining output states instead.

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: 'Returns connection status and URLs.' This is a specific verb and resource, and it distinguishes from sibling tools like 'authenticate' (which handles auth flows) and 'show_version' (which reports version info). It also defines the exact output states, making 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 implies when to use it (checking connection status) by describing what it returns, but it does not explicitly contrast with alternatives like 'authenticate' or provide when-not-to-use guidance. It gives context on the two states but no direct usage 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.

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

Beyond annotations (readOnlyHint=false, openWorldHint=true), the description discloses key behaviors: invoke works even when the MCP is not installed, returns a connect link when credentials are needed, returns a checkout/top-up link when paid and wallet is empty, and requires workspace owner/admin for writes. It also notes that install makes an MCP permanent and that search/describe flag installed status. This is rich behavioral context with 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 dense and front-loaded with the core purpose, then the flow, key invoke behavior, usage guidance, permissions, and prompt library. It is a long single paragraph but every sentence adds value. It could be better structured with bullets or separation of the prompt library section, but it is not padded or redundant.

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 complexity (23 params, no output schema, minimal annotations), the description covers the main flows, auth, billing, permissions, and the prompt library. It explains what invoke returns in special cases (connect/checkout links) but does not describe return formats for search/describe/list_tools, which would be expected in the absence of an output schema. Still, it is largely complete for such a broad 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?

With 23 parameters and 0% schema description coverage, the description must compensate. It does explain the action enum values and the high-level roles of tool_id, mcp_id, and the prompt-related actions, but many parameters (limit, query, immediate, tier_slug, prompt_body, prompt_vars, cancel_reason, etc.) remain undocumented. The description adds meaning for the core flow but leaves significant gaps for a tool with this many parameters.

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 is 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It uses specific verbs (search, describe, invoke, install) and resources (MCPs, tools, prompt library), and distinguishes itself from siblings like authenticate, connect, and toolkit_info by covering the full catalog and execution 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 provides explicit when-to-use guidance: 'Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile... so you pick the right tool_id → invoke RUNS that tool.' It also contrasts invoke vs install ('prefer invoke for a single/occasional use'), explains list_tools, subscribe/cancel, report_bug, request_mcp, and the prompt library actions, giving clear alternatives.

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 covered. The description adds valuable context: the payment per query, lack of platform credentials, non-confidential nature of data, and LGPD responsibility. This goes beyond the annotations and helps the agent understand the operational and legal 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 concise, with two sentences that front-load the main purpose and then add operational and legal context. No redundant information is present, though the LGPD mention could be considered tangential, but it is relevant for compliance-aware agents.

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 2 optional params and no output schema. The description covers the source, payment, and legal aspects but omits what the response contains (e.g., return format, fields) and fails to explain parameter usage. Given the lack of output schema, this is a notable gap, but the tool's simplicity and good annotations keep it at a minimally complete level.

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 has 2 optional parameters (cpf, nome) with 0% schema description coverage, so the description must compensate. However, the description does not mention these parameters at all, leaving the agent to infer their meaning from names alone. No guidance on whether at least one is required or how they interact is provided.

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 a query for public servant information from the Brazilian Transparency Portal, using the verb 'consulta' (query) and resource 'Servidor Público'. It distinguishes itself from sibling tools (authenticate, connect, etc.) by focusing on the specific official data source and 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 clear context: it is hosted, requires prepaid credit, and queries official Brazilian public data. It implies when to use it (when needing public servant info from official sources) but does not explicitly state exclusions or alternatives. Still, it gives enough guidance for appropriate 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?

Annotations already indicate idempotent and non-destructive behavior, but the description adds no extra context such as side effects, permissions, or rate limits. It only mentions including conversation for reproduction, which is more about parameter usage than behavior.

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 concise (two sentences), front-loaded with the purpose, and contains no unnecessary information. It directly states what the tool does and one key parameter instruction.

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, but the description lacks details about the 'context' parameter and does not explain what happens after reporting. It provides the core purpose and one parameter, but not full completeness for a user unfamiliar with 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?

The schema has no per-field descriptions (0% coverage), so the description must compensate. It explains the 'conversation' parameter ('Include the conversation array with recent messages for reproduction') but does not explain 'message' or 'context'. Partial compensation results in a mid 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 clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' This is a specific verb and resource, and it distinguishes from sibling tools like authenticate, connect, 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 gives the action but does not explicitly state when to use this tool versus alternatives. It implies usage for bug reporting, but lacks direct comparison or situational 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?

Annotations already declare readOnly and idempotent, and description adds that it shows versions of both MCP platform and adapters. 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?

Single sentence, concise and front-loaded. No wasted 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?

For a simple no-parameter version tool, the description is complete. No output schema or complex behavior to explain.

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?

Tool has zero parameters, and schema coverage is 100% (vacuously). No parameter documentation needed, but description adds informational value about what is reported.

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 shows current MCP platform and adapter versions. Distinct from siblings 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?

No explicit when-to-use guidance, but the tool is self-explanatory for a version check. Implied usage is to check versions, no need for alternatives in this context.

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 and non-destructive behavior. The description adds no further transparency about side effects, permissions, rate limits, or other behavioral aspects beyond the return content.

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 main action and listing return items concisely. No unnecessary words or repetition, making it highly efficient.

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 no parameters and no output schema, the description provides a reasonable list of what will be returned (state, MCPs, status, accounts, catalog counts). It lacks specific format details but is adequate for a simple state-check 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 schema coverage is complete. According to the rubric, a baseline of 4 applies for zero params, and the description doesn't need to add parameter details 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 action ('Returns') and resource ('current toolkit state'), enumerating the specific details (installed MCPs, connection status, accounts, catalog tool counts). This is specific and distinguishes the tool from potential siblings.

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 no guidance on when to use this tool versus alternatives (e.g., when to check state before connecting or after). It only describes what it returns, not the appropriate usage context.

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