MPA: PesqBrasil

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

The description reveals important behaviors not covered by annotations: it can either return a login link (when called with no args) or accept a token for immediate session login. It also clarifies the durability of each method (non-expiring vs. session-only), which goes well beyond the idempotent readOnly/destructive 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?

The description is a bit longer than necessary, but every sentence contributes: the opening context, the recommended permanent method, and the alternative session-based method. It is well-structured with 'Best' and 'Or' to guide the user. Minor redundancy with 'log in in the browser' could be tightened, but it remains focused.

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 has a single optional parameter and no output schema. The description covers the essential usage scenarios and expected behavior, but it does not detail return values beyond stating that the no-arg call returns a link, nor does it address error cases or how this integrates with sibling tools like 'connect'. Given the simplicity, this is reasonably complete but leaves minor gaps.

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 one undocumented 'token' property with 0% coverage. The description explains the token's format (JWT), its optionality, the exact call pattern ({ token: '<jwt>' }), and the behavior when omitted (returns the link). This fully compensates for the lack of schema 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's purpose: authenticating IDE agents to MCP.AI. It specifies the action (log in, obtain token) and distinguishes this from sibling tools by focusing on authentication specifically, with concrete methods for permanent and session-based access.

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 guidance on when to use two modes: add a header for a permanent connection vs. passing a token for session-only login. However, it does not explicitly contrast this tool with alternatives like 'connect', so it lacks explicit exclusions or alternative tool 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 readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by explaining the response specifics: authenticated flag, pending array, and connect_url when credentials are missing. This goes beyond the annotations and clarifies behavioral 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 two sentences, front-loaded with the core action and then providing conditional details. No superfluous information; every sentence earns its place. Highly 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?

Given the absence of an output schema, the description adequately explains the return values and conditional behavior. It covers the main use cases (connected vs. missing credentials) and mentions the URLs. It could elaborate on the exact format of URLs or pending array, but for a simple status tool, it is sufficiently complete.

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 has no obligation to explain parameters. The baseline for 0 parameters is 4. The description does not mention parameters, which 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 clearly states the action (returns connection status and URLs) and specifies the resource (connection status for the toolkit). It does not explicitly differentiate from sibling tools like authenticate, but the focus on status checking is distinctive. The purpose is clear but lacks an explicit note about when to prefer this over alternatives.

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 about when it returns connection status and the two scenarios (all connected vs. missing credentials). It implies its use for checking connection state but does not mention exclusions or alternative tools. The context is sufficient for most cases.

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?

This is far more transparent than the sparse annotations alone, which only say readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description discloses that invoke runs one-off even when the MCP is uninstalled, that install makes the MCP permanently appear in the toolkit, that credential/payment links must be opened by the user before retrying, and that writes require workspace owner/admin. It also flags installed_in_toolkit vs installed_in_workspace states. 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 dense and long, but the length is largely justified by the tool's 14 action routes and dual marketplace/prompt-library role. It front-loads the core purpose, then explains the key invoke semantics, then covers supporting actions. However, it is one large unbroken paragraph with no separators or bullets, which makes the many distinct behaviors harder to scan quickly.

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 14 actions, 23 params, no output schema, and minimal annotations, this description is quite complete: it explains the primary flow, credential/payment handling, permanent vs one-off installation, owner/admin permission requirements, and the prompt-library subcommands. Some gaps remain—the general return shape of search/describe/list_tools isn't described, and some peripheral params still lack context—but the description covers the high-risk and high-usage behaviors 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 23 parameters and 0% schema description coverage, the description carries a heavy burden. It does explain the meaning of several key params implicitly: action (search/describe/invoke/install/etc.), mcp_id (the MCP's identity), tool_id (the chosen tool within an MCP), arguments (tool invocation params), and prompt_vars (fills {{variables}}). However, many parameters remain unaddressed (limit, immediate, tier_slug, cancel_reason, prompt_targets, request_details, etc.), so the description only partially compensates for the schema's lack of explanations.

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 then enumerates concrete intents ('find an MCP that does X', 'consulta um CPF') and maps them to a core flow (search → describe → invoke), making the tool's purpose unmistakable and distinct from simple listings. It also clearly separates the MCP-management side from the prompt-library side.

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 explicit when-to-use guidance: 'prefer invoke for a single/occasional use,' 'Use install only to make an MCP PERMANENT,' 'list_tools lists what is callable right now,' and 'request_mcp asks us to build a NEW MCP when nothing fits.' It also explains credential and payment fallback retry behavior, so an agent knows what to do when invoke returns a connect or checkout link.

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, so the description adds value beyond that by disclosing that the tool is hosted by the platform, requires no platform credentials, incurs a per-query cost with prepaid credit, returns non-confidential data, and places LGPD controller responsibility on the client. These are meaningful operational and legal behaviors not covered by 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 relatively concise, front-loads the main purpose ('consulta em fonte oficial'), and uses clear sentences. It includes some legal/financial details that could be seen as extraneous, but they are brief and do not significantly bloat the text.

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?

While the description provides the high-level purpose and some operational context (payment, LGPD), it omits essential information about the input parameters (CPF/RGP) and the return format (no output schema either). This leaves the tool under-specified for reliable invocation, especially given the complete absence of parameter semantics.

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 two parameters (cpf, rgp) with zero description coverage, and the description does not mention either parameter or explain what they mean or how to format them. The agent is given no semantic guidance for constructing a valid query, making the tool effectively unusable without external knowledge.

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 ('consulta') for official Brazilian sources and bodies, with a specific resource ('fontes e órgãos oficiais brasileiros'). It distinguishes from siblings like authenticate or marketplace, though it does not specify exactly what kind of data is returned (e.g., CPF/RGP records), leaving some ambiguity.

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 usage context is implied: this tool is for querying public, non-confidential Brazilian official data, and use is paid via prepaid credit. However, it does not explicitly state when to use it over alternatives (though none are obvious among siblings) or what conditions warrant not using it. The LGPD responsibility note gives legal context but not direct usage direction.

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 indicate idempotentHint=true, suggesting repeated calls have no side effects, and destructiveHint=false, so no destructive actions. The description adds that the conversation array should be included for reproduction, which is helpful behavioral context beyond annotations, but it does not mention side effects such as whether the report is stored or sent externally, or any rate limits or authentication requirements.

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, consisting of two sentences. It front-loads the primary purpose and then provides a practical instruction on including the conversation array, which is efficient. No redundant phrasing, but it could be slightly more structured by explicitly listing parameters, though current form is acceptable.

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 moderate complexity (3 params, no output schema, no enums), the description is adequate but not comprehensive. It covers the tool's purpose and gives a reproduction hint, but lacks details on how the conversation should be formatted, what happens after submission, and how to handle optional context. There is room for improvement in helping the agent use the tool effectively.

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 must clarify parameter usage. It mentions the conversation array but does not explain the 'message' or 'context' parameters beyond the schema's basic types and defaults. The 'context' field's purpose remains unclear, and the description does not compensate fully for the lack of schema descriptions, so it only partially adds value.

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: reporting bugs, missing features, or sending feedback. It distinguishes itself from siblings by focusing on feedback/reporting actions rather than authentication or information retrieval, though it doesn't explicitly mention alternative tools for other actions.

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 reporting bugs or feedback, and instructs to include the conversation array for reproduction, giving a clear context. However, it does not provide explicit guidance on when NOT to use this tool or which sibling tool to use instead for similar purposes, leaving some ambiguity.

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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds the term 'current,' implying it queries live environment state, but does not disclose other behavioral details. This is minimal but acceptable given 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 concise sentence: 'Show the current MCP platform and adapter versions.' It is front-loaded with the action and resource, contains no unnecessary words, and is easy to parse quickly.

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 (no parameters, no output schema, full annotation coverage), the description fully captures its function. There is no missing context about inputs or return values because none exist. The description is complete for a read-only version query 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 there is no parameter semantics to document. The schema is an empty object with complete coverage, and the description adds no parameter information, which is appropriate. The baseline of 4 applies for a parameterless 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 'Show' and names the exact resource: 'current MCP platform and adapter versions.' This clearly distinguishes it from sibling tools like toolkit_info, which likely covers broader information. The purpose is immediately obvious 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?

No explicit guidance is given about when to use this tool versus alternatives. However, the name and description imply it should be used when version information is needed, and there are no competing version-specific siblings. Usage is implied rather than stated, matching a 3.

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 adds information about the content returned but does not disclose additional behavioral traits beyond the annotations. Annotations already indicate readOnly, idempotent, and non-destructive behavior; the description reinforces this by stating it returns state but does not discuss potential errors, latency, or 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 a single, well-structured sentence that quickly conveys the tool's function and the specifics of its output. It is concise, free of fluff, and uses a clear list format to enumerate the returned data.

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 gives a good high-level overview of the tool's output, mentioning the key categories of data. However, it does not specify the format or structure of the return value (e.g., as a list, object, or specific fields). Given that there is no output schema, a bit more detail could enhance completeness, but the current description is adequate.

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 in the schema, so the description does not need to explain parameter semantics. The lack of parameters is itself self-explanatory, and the description appropriately focuses on the output. A score above 3 is given because the description is complete given the absence of 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's purpose: returning the current toolkit state, and enumerates exactly what information is included (installed MCPs, connection status, accounts, number of catalog tools). This specificity 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 provides no guidance on when to use this tool versus alternatives. It does not mention scenarios where this tool is preferred, nor does it indicate any prerequisites or exclusions. Users are left to infer its use case from the name alone.

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