Portal da Transparência: Convênios e Acordos

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

The description adds meaningful behavioral context beyond the annotations: it explains that calling with no args returns a link, that token-based login is session-only, and that config-header auth is permanent and non-expiring. This complements the idempotentHint and does not contradict any annotation.

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 and front-loaded with the tool's context. It uses three sentences to cover the main flow, the recommended permanent setup, and the session-only alternative. The third sentence is slightly dense with multiple clauses, but every part contributes useful 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?

For a tool with no output schema and one optional parameter, the description covers the essential invocation patterns and the user-visible flow. It explains both the no-arg and token-arg cases, plus the recommended config approach. It does not detail error handling or response format, but that is not critical for selection and invocation.

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 defines 'token' as an optional string with no description. The description compensates by explaining that token is a JWT pasted by the user and that omitting it triggers the link-returning flow. This provides essential meaning beyond the raw schema.

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: authenticating to MCP.AI for IDE agents. It specifies the login flow (browser login, copy token) and distinguishes between permanent config-based auth and session-only token auth, making the tool's role 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 explicit usage guidance: add the token to server config for a permanent connection, or call with a token for session-only login, or call with no args to get the login link. It does not explicitly compare against sibling tools, but the in-tool alternatives are clearly explained.

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 the description adds specific behavioral details about response conditions (authenticated:true when connected, connect_url when credentials missing), which goes beyond the annotations. No contradictions.

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 that efficiently convey purpose and key behavior with no redundancy. 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 parameterless status tool with no output schema, the description covers the main return conditions. It could mention the shape of the response more fully, but it's adequate given the 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?

With zero parameters, the schema coverage is 100%, so the description adds no parameter semantics but also has nothing to explain. Baseline of 3 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?

Clearly states 'Returns connection status and URLs' which distinguishes it from siblings like 'authenticate' (which performs authentication) and other informational tools. It also specifies two distinct result scenarios, making the tool's function 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?

Provides clear context for when to use it (to check connection status) but does not explicitly mention alternatives or when not to use it, so it earns a 4 rather than a 5.

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?

Without any param docs and with sparse annotations (readOnlyHint=false, no destructive hint), the description carries the full burden and delivers richly. It reveals critical non-obvious behaviors: invoke runs one-off without installing or bloating the tool list, auth failures produce a connect link, insufficient wallets produce a checkout link, and the agent should retry after the user acts. It also flags the subtle difference between installed_in_toolkit and installed_in_workspace and the permission requirements for writes. 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 unusually dense; it achieves remarkable signal-per-word. It front-loads with the core flow, calls out a 'KEY' insight, uses arrows (→) for sequence, and clearly separates the marketplace from the prompt library feature. It loses a point for being a wall of text that would benefit from bullet points or paragraph breaks, but each section genuinely 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?

Given that this is a large, multi-action marketplace with 23 optional parameters and no output schema, the description addresses the crucial runtime behaviors an agent needs: the one-off vs. permanent install distinction, payment/connect link flows with a retry signal, workspace-level permissions, and the distinction between MCP tools and prompt-library entries. Despite no param docs or output schema, an agent has enough to select the right action and understand side effects.

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 coverage and 23 parameters, the description needed to compensate heavily, and it does a solid job on the action parameter, enumerating semantics for each value (search, describe, install, invoke, subscribe, cancel, report_bug, request_mcp, search_prompts, get_prompt, publish_prompt, list_tools) and explaining the tool_id/query flow. It doesn't address every param (tier_slug, limit, prompt_* fields, cancel_reason are untouched), so it earns strong but not perfect marks.

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 is built around specific verb+resource phrases: 'the in-platform catalog... AND the way to run them', 'action=search discovers MCPs by intent → describe returns one MCP's full profile → invoke RUNS that tool'. It distinguishes itself from siblings by detailing exactly where it fits in the lifecycle and even covers the separate prompt-library feature. The purpose is specific, scoped, and 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?

Explicit when-to-use and when-not-to-use guidance abounds: 'Use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use', 'list_tools lists what is callable right now', and 'request_mcp asks us to build a NEW MCP when nothing fits'. It clearly lays out authorization boundaries ('Writes... require workspace owner/admin') and the retry-after-connect-link workflow, giving the agent a decision procedure rather than just a definition.

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 false. The description adds operational details: hosted by platform, prepaid credit required, data is non-confidential, and LGPD compliance, enriching transparency without contradicting 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 concise, with four sentences that front-load the purpose and then add relevant operational and legal context. It avoids unnecessary verbosity while covering key points.

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 one-parameter query tool with no output schema, the description covers purpose, source, payment, and legal aspects. However, it omits parameter clarification and response format details, leaving some ambiguity about expected behavior and output.

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 description does not explain the 'convenente' parameter, and schema coverage is 0%, leaving the agent without any guidance on what value to provide. This is a critical gap for a single required 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 queries the Transparency Portal for Convênios and Acordos, using the verb 'consulta' and a specific resource. It distinguishes itself from sibling tools like authenticate or connect by specifying it accesses official Brazilian data.

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 context on when to use the tool (for official data, pay-per-query, no platform credentials) but does not explicitly mention alternatives or exclusions. It implies usage for agreement queries, which is clear enough for an agent.

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 this is a non-readOnly, idempotent, non-destructive operation. The description adds useful context about including the conversation for reproduction, but does not explain what happens after the report is sent, whether confirmation is returned, or any other side effects.

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 with no filler. Each sentence earns its place: the first states the tool's purpose, and the second gives a key usage 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?

For a simple feedback-reporting tool, the description is minimally viable, but it leaves gaps because there is no output schema and parameter coverage is low. It could usefully document the message and context parameters and what happens after submission.

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 parameter explanations. It only meaningfully explains the conversation parameter (recent messages for reproduction), while message and context are left mostly implied; context is not described at all.

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 reports a bug, missing feature, or feedback, using specific verbs and resource types. It is easily distinguishable from the sibling tools, none of which cover issue reporting or feedback.

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 context for when to use the tool: for bug reports, feature requests, or feedback, and instructs the user to include recent conversation for reproduction. It does not explicitly name alternatives or state when not to use it, but the sibling list makes alternatives obvious.

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 is fully consistent with annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), all declaring a safe read operation. The description adds mild value by specifying the two version components (MCP platform and adapter), and nothing contradicts the structured hints.

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 11-word sentence that is perfectly front-loaded with the verb 'Show' and resource. Zero wasted words—every part of the description 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?

Given the tool's trivial complexity (0 params, no output schema, rich annotations covering safety), the description is complete. There is nothing meaningful missing for an agent to invoke this tool 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?

With 0 parameters and schema coverage at 100% (vacuously), the baseline is 4 per the rubric. There is nothing for the description to add on parameters, and no undocumented parameters 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 uses a specific verb ('Show') with a clear resource ('the current MCP platform and adapter versions'), fully explaining what the tool does. It distinguishes itself from sibling tools like authenticate and connect by scoping to version display.

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?

For a zero-parameter version tool, the context is self-evident—the description makes it clear this is the tool to call when version info is needed. No exclusions or alternatives are needed at this complexity level, and the sibling list confirms this is the sole version-related tool.

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 cover read-only, idempotent, non-destructive behavior. The description adds value by detailing the specific content of the state (installed MCPs, status, accounts, tool counts), which helps set expectations. However, it doesn't discose anything about the retrn format or potential latency. Since annotations cover safety, the added context earns a solid 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 a single concise sentence that effectively lists all the key information points without fluff. It's front-loaded with the core purpose and then enumerates specifics. Every word 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?

Given the tool's simplicity (zero params, no output schema), the description is quite complete. It manages expectations about what state is returned. Slightly more detail on the 'connection status' and 'accounts' could be added, but for such a simple tool, the coverage is strong. The sibling tools are different enough that there's no confusion.

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?

This tool has zero parameters, so there are no parameters to explain. The schema covers 100% (vacuouslt), and the description provides a clear overview of what the tool returns. Baseline for zero parameters is 4, and the description enriches that by detailing the output fields, justifying the maximum.

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 returns the current toolkit state and enumerates exactly what's included: installed MCPs, connection status, accounts, and catalog tool counts. This is a specific, informative purpose that distinguishes it from siblings 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 makes it evident that this is for inspecting state rather than performing actions, which is useful context. It doesn't explicitly mention when not to use it or point to alternatives, but the clear state-reporting nature implicitly guides usage. Given sibling tools like connect and authenticate, a small explicit distinction could be added, but it's not necessary.

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