Indicadores PJ (Transparência)

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

Annotations already declare idempotent and non-destructive behavior. The description adds context about session-only vs permanent connection, and that no args returns a link. No contradictions 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 moderately sized and front-loaded with the core purpose. The IDE agent preamble adds context but could be trimmed. Overall, every sentence serves a purpose.

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 auth tool with an optional token and no output schema, the description covers the essential flows: pasting a token, getting a link, and configuring a permanent header. It doesn't detail the response shape but says 'get the link', which is sufficient.

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 lists a token string with no description. The description explains the token is a JWT pasted by the user, and that omitting it triggers a login link. This fully compensates for the 0% schema 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 authenticates the MCP.AI server for IDE agents, with specific actions: pasting a JWT token for session login or getting a browser link. It explicitly differentiates itself from siblings by focusing on authentication.

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 scenarios: permanent connection via config header, session-only via token, or no args to obtain a link. The 'Best' recommendation adds practical guidance, though it doesn't explicitly exclude other 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 declare readOnly and idempotent hints, and the description adds valuable behavioral details about response states: authenticated:true and connect_url when credentials are missing. 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?

The description is two concise sentences, front-loaded with the main purpose, and every clause adds meaningful information. There is no wasted wording.

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 main states (all connected vs. missing credentials) but does not address partially-connected scenarios. Given the tool's simplicity (no params, no output schema), this is reasonably complete, but there is a minor gap.

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 schema is fully covered. No parameter information is needed, and the description does not need to compensate. Baseline of 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 clearly states the tool returns connection status and URLs, with specific outcome conditions. It is distinct from siblings like authenticate, which performs a different 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 implies this is for checking connection status, but does not explicitly state when to use it versus alternatives, nor does it provide exclusions. The conditional outcomes give some context, but no direct 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?

Goes well beyond the minimal annotations: explains the one-off nature of invoke (no toolkit bloat), the connect link for missing credentials, checkout/top-up link for empty wallet, admin requirement for writes, and the distinction between MCP catalog and prompt library. No contradictions 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 it is highly structured (introduction, core flow with arrows, KEY callout, prompt library section). The density is justified given the platform contains 14 actions; still, it could be trimmed (e.g., the 'consulta um CPF' example) and the mixed-language word 'pontualmente' slightly hurts clarity.

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 umbrella tool with 23 parameters, no output schema, and 14 actions, the description covers the full lifecycle: discovery, describe, invoke, install, billing, permission requirements, prompt library, and how to request new MCPs. It equips an agent to choose and run the correct action in most scenarios.

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 teaches the central action parameter by explaining what each action does (search, describe, invoke, install, list_tools, subscribe, cancel, report_bug, request_mcp, prompt actions). It also explains the relationship between mcp_id, tool_id, and arguments through the core flow. However, many of the 23 parameters (e.g., immediate, tier_slug, conversation, prompt_vars format) are not individually described, leaving some gaps.

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 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' clearly defining the verb (catalog/run) and resource (MCP/tool). It covers the full action set, distinguishing it from sibling tools like toolkit_info or report_bug by describing itself as the central discovery and invocation hub.

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?

Explicitly lays out the core flow (search → describe → invoke), contrasts invoke vs install ('prefer invoke for a single/occasional use'), notes list_tools for callable tools, request_mcp for new MCPs, and specifies when billing/subscribe/cancel apply. This gives the agent clear selection logic.

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 safety information (idempotentHint=true, destructiveHint=false, readOnlyHint=false). The description adds minimal behavioral context beyond this, such as the need to include a conversation array for reproduction, but does not disclose side effects (e.g., data sent externally), response behavior, or prerequisites like authentication. It adds some value but does not fully enrich the behavioral picture.

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 long, front-loaded with the primary purpose, and contains no filler. It efficiently conveys the core action and a key usage detail. Every sentence contributes meaningful 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 3 parameters, no output schema, and no enums, the description is fairly complete in conveying purpose and the conversation parameter, but it leaves the 'context' parameter unexplained and says nothing about what happens after reporting. It is adequate for a simple tool but has clear gaps in parameter coverage and behavioral outcomes.

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 compensate. It explains the 'conversation' parameter ('recent messages for reproduction') and implicitly clarifies 'message' as the reported text, but it completely omits the 'context' parameter. This leaves one of three parameters semantically undocumented, so the description only partially compensates for the schema coverage gap.

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 with a specific verb ('Report') and explicit resources ('bug, missing feature, or send feedback'). This clearly distinguishes it from all sibling tools, which are unrelated (e.g., authenticate, connect, marketplace). The purpose is immediately understandable 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?

The description provides clear context for when to use the tool: whenever the user wants to report a bug, request a feature, or give feedback. While it does not explicitly mention alternatives or exclusions, the sibling list contains no similar reporting tool, so the usage context is evident. The lack of explicit 'when not to use' guidance prevents 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces these by saying 'Show' and adds context that it reports platform and adapter versions. It does not describe output format, but for a low-risk read-only call this is sufficient.

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 declarative sentence immediately states the tool's purpose without wasted words. It is front-loaded and perfectly sized for the tool's simplicity.

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 zero-parameter read-only tool with strong annotations, the description is adequately complete. It specifies what versions are shown, though it does not detail the exact response structure; acceptable given no output schema and the straightforward nature of 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 tool has zero parameters, so the input schema fully covers the input side. The description appropriately avoids adding parameter details that do not 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?

Description uses specific verb 'Show' and names the exact resources: 'current MCP platform and adapter versions.' This clearly distinguishes it from sibling tools like authenticate, connect, and report_bug, leaving no ambiguity about its function.

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 the tool is for retrieving version information but provides no explicit guidance on when to use it versus alternatives, nor any exclusions. For a simple version-check tool this is acceptable but still lacks overt 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 already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the description's job is lighter. The description adds meaningful context beyond annotations by specifying what data is returned (connection status, accounts, tool counts), which clarifies the tool's behavior without contradicting 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?

One sentence, front-loaded with the verb and resource, followed by a compact list of return details. No redundancy or filler, making it 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 tool has no parameters and strong annotations, the description is complete enough. It enumerates the main return items (installed MCPs, statuses, accounts, catalog tool counts), so even without an output schema, the agent understands 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 schema coverage is 100% by default. The description does not need to explain parameter semantics, as there are none, so the baseline of 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 a specific verb ('Returns') and clearly defines the resource (toolkit state) with enumerated details (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from siblings like authenticate, connect, and show_version, which serve 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 use when needing an overview of toolkit state, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. Sibling tools like show_version might seem similar, but no direct comparison is given.

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 valuable behavioral context beyond annotations: no credentials needed, pay-per-query with prepaid credit, and that the data is public access, not private. This enriches the readOnly/idempotent hints provided in 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 and front-loaded with purpose, but includes some legal boilerplate (LGPD) that slightly dilutes the core message. Still, it's reasonably concise.

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 purpose, authentication, cost, and data sensitivity, but lacks detail on the 'completo' parameter and the return format. Given the absence of an output schema, more information would improve completeness.

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 explains the CNPJ parameter is the lookup key, but provides no explanation for the 'completo' boolean parameter. With 0% schema description coverage, the description should clarify all 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 retrieves indicators (sanctions, agreements, contracts) for a company on the Transparency Portal using CNPJ, which is a specific verb+resource and 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 implies usage context (querying company indicators via CNPJ) but does not explicitly state when to use this tool vs alternatives or provide exclusions. Sibling tools are unrelated, reducing the need, but no explicit guidance is given.

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