Portal da Transparência: Repasse de Verba

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

The description adds meaningful behavioral context beyond the annotations: it explains the authentication workflow, the permanent vs session-only distinction, and that no-args returns a link for browser login. It is consistent with the annotations, which already signal idempotency and non-destructive 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 three sentences and densely informative, with the primary purpose stated first and the parameterization explained with concrete examples. Every sentence adds value, and code formatting helps distinguish the two invocation patterns.

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 simple one-optional-parameter schema and no output schema, the description is complete: it covers purpose, invocation modes, user interaction, and setup guidance. It gives an agent enough detail to select the tool and call it correctly in either mode.

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 only shows an optional string token with no description, but the tool description fully explains that 'token' is a JWT access token and that omitting it triggers the link-returning flow. This fully compensates for the 0% schema description coverage.

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 handles MCP.AI authentication for IDE agents, explaining the browser login and token flow. It is more than a tautology and uses concrete verbs like 'log in' and 'call', though it does not explicitly distinguish itself from the sibling tool '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?

It gives explicit usage context: adding the token to the server config for a permanent non-expiring connection, or pasting it for session-only login, and calling with no args to get the link. It lacks an explicit 'when not to use' or mentions of alternative sibling tools, but the guidance is 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=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds value by detailing the two output states (authenticated vs. missing credentials) and specific fields (authenticated, pending, connect_url, per-install URLs), which goes beyond the annotations. It does not contradict 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 two sentences, front-loaded with the main purpose, and efficiently conveys conditional results. Every clause adds value with no fluff or redundancy.

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 zero parameters and no output schema, the description covers the essential behavior: it returns connection status and URLs, explains two states (all connected vs missing credentials), and mentions key fields (authenticated, pending, connect_url). This is complete for the tool's simplicity.

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. According to guidelines, baseline for 0 params is 4. The description doesn't need to explain parameters since there are none. It doesn't add any parameter-related info but doesn't need to.

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 'Returns connection status and URLs,' which is a specific verb+resource combination. It clearly distinguishes from sibling tools like authenticate (auth flow) and show_version (version info). The conditional behavior (authenticated vs missing credentials) further clarifies its role as a status checker.

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 by explaining what it returns in different states, but it doesn't explicitly say when to use it or when not to. It doesn't name alternatives or exclude other tools. However, the context is clear enough for an agent to infer it's for checking connection status. Lacks explicit exclusion guidance, but is still helpful.

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 well beyond the annotations by disclosing that writes require workspace owner/admin, that invoke runs one-off without bloating the toolkit, that missing credentials return a connect link, and that empty wallets return a checkout link requiring retry. It also explains the prompt library's behavior with shareable links. 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 dense single paragraph but front-loaded with the primary purpose and core flow. Every sentence adds value, but the lack of bullet points or section breaks makes it harder to scan. For a tool with 14 actions and 23 parameters, the length is justified.

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 (14 actions, 23 params, no output schema), the description covers the main flows, permissions, edge cases (connect/checkout links), and the prompt library. It provides enough context for an agent to select the correct action and understand the consequences, even without 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?

Schema description coverage is 0%, so the description must compensate. It explains the meaning of key parameters (action, mcp_id, tool_id, arguments, prompt_* fields) through the core flow and action list. However, 23 parameters exist and some (limit, query, immediate, tier_slug, conversation, cancel_reason) are not explicitly described, though many are self-explanatory from names/defaults.

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 official mcp.ai marketplace and catalog, with a specific verb+resource ('search/describe/invoke/install') and a core flow. It distinguishes itself from siblings by positioning itself as the in-platform catalog and runner, while siblings like authenticate/connect/toolkit_info serve different functions.

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 guidance is provided: 'prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT', 'list_tools lists what is callable right now', and each action (subscribe/cancel/report_bug/request_mcp) is given a one-line purpose. This clearly tells the agent when to use this tool and how to choose among its many actions.

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?

Even though annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds meaningful behavioral and contractual context: the tool is hosted by the platform, requires no platform credentials, is paid via prepaid credit, queries public non-confidential data, and the client is the LGPD data controller. This goes well 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 short, front-loaded with the core purpose, and every sentence adds relevant information about source, cost, credentials, data sensitivity, or legal responsibility. There is no filler or redundancy.

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, official source, payment model, and LGPD context, but it lacks parameter semantics and return-value expectations. With no output schema and undocumented parameters, the agent is left without enough detail to safely and correctly invoke the tool in all cases.

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% and the description does not explain the meaning, format, or allowed values of 'ano', 'localidade', or 'tipo'. The description provides no parameter-level guidance, so the agent cannot reliably determine how to fill the arguments, especially 'tipo'.

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 consultation/query operation against the official Brazilian transparency portal for fund transfers ('Portal da Transparência: Repasse de Verba, consulta em fonte oficial'). It specifies the resource and action, and it is easily distinguished from the sibling tools (auth, marketplace, bug reporting, etc.).

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 context for when to use the tool: to query official Brazilian public data available to citizens, with no platform credentials and prepaid per-query billing. It does not explicitly state exclusions or alternatives, but the context is clear enough and no sibling tool competes for the same purpose.

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 provide readOnly=false, idempotent=true, destructive=false, so the description doesn't need to restate those. The description adds the useful requirement to include conversation for reproduction, but doesn't disclose what happens after reporting (e.g., response format, rate limits, or authentication needs). With annotations covering the basic safety profile, this is acceptable but not rich.

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, compact sentence that immediately states the tool's purpose. It is front-loaded with the core action and gives a necessary instruction (including the conversation) without any irrelevant detail.

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 reporting tool with no output schemaamente, the description adequately covers the primary use case and the key parameter (conversation). The lack of mention of the context parameter is a minor gap, but the tool's simplicity and optional context (defaulting to empty) make the description sufficient for an agent to use it 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?

Schema coverage is 0% (no parameter descriptions). The description clarifies the purpose of the conversation parameter (reproduction), but calls it an 'array' while the schema defines it as a string (likely JSON-encoded). The context parameter is completely unaddressed. Partial compensation, but with potential for confusion.

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 ('Report a bug, missing feature, or send feedback') and identifies the resource (the tool itself for submitting reports). It clearly distinguishes its purpose from sibling tools like authentication or marketplace 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?

Provides clear guidance on what to report and emphasizes including the conversation array for reproduction. No competing alternatives exist among siblings, so exclusions are unnecessary, but it lacks explicit when-not-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?

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description does not need to repeat these. It adds specificity by highlighting 'current' versions and the involved components (platform and adapter), which reinforces the non-mutating nature. No contradiction exists.

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, concise sentence with no unnecessary words. It conveys the essential information efficiently, earning a perfect score for structure and economy.

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?

No output schema is provided, but the description gives a clear idea of what the tool returns (version numbers for platform and adapter). It does not specify the exact format or structure, but for a simple version-check tool, this level of detail is sufficient. The description is complete enough for typical usage.

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 schema coverage is effectively 100%. The description does not add parameter-related details, but none are needed. Baseline score of 3 is appropriate as the description doesn't enhance parameter understanding beyond what the schema provides.

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 the tool's purpose unambiguous. It distinguishes itself from sibling tools like 'toolkit_info' by focusing on version information.

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 versus alternatives, nor does it mention any conditions or caveats. However, given its simple and self-explanatory nature, the intended usage is implicitly clear—likely for checking version numbers. Still, explicit guidance is missing.

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 useful behavioral context by detailing the exact state information returned, which goes beyond mere 'returns toolkit info.'

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 wasted words. It immediately states the action and then lists the concrete contents of the returned toolkit state.

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 input schema parameters and no output schema, the description carries full burden for explaining return content, and it succeeds by naming the main elements: MCPs, connection status, connected accounts, and catalog tool counts. This is complete for a simple read-only state 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?

There are zero parameters and an empty input schema, so the baseline is 4. The description does not need to explain parameters and instead focuses on what the tool returns, which is appropriate for a no-argument introspection 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 description uses a specific verb ('Returns') with a clear resource ('current toolkit state') and enumerates exactly what is included: installed MCPs, connection status, accounts, and catalog tool counts. This clearly distinguishes it from sibling action-oriented tools like authenticate, connect, and report_bug.

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 status but does not explicitly state when to prefer this over alternatives like show_version or marketplace. It provides a clear context but no when-not-to-use guidance or alternative references.

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