Portal da Transparência: Programa de Erradicação do Trabalho Infantil - PETI

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

The description adds behavioral context beyond the annotations: it explains the browser login flow, distinguishes between non-expiring header tokens and session-only JWTs, and describes what happens when called with no arguments. This complements the idempotentHint annotation without contradicting it.

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 somewhat long but structured with clear options (permanent vs. session vs. no-args). The information is front-loaded with the core purpose and each sentence provides necessary usage details, though it could be tightened without losing meaning.

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 an authentication tool with no output schema and a single optional parameter, the description covers the two main usage paths, the browser interaction, and the token semantics. It lacks details about post-authentication responses or error handling, but is otherwise complete enough for an agent to invoke 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 schema description coverage at 0%, the description compensates by explaining that the `token` parameter is a JWT for session-only authentication, used after the user pastes it. It also clarifies that the parameter is optional and that omitting it returns a login link.

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: authenticate a user by logging in via browser and obtaining an access token. It distinguishes itself from siblings by focusing on authentication rather than general connectivity, and it explicitly describes two usage modes (permanent header config and session token).

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 each mode: configuring the Authorization header for a permanent connection, pasting a token for session-only login, or calling with no arguments to receive a login link. It does not explicitly mention alternatives among siblings or when not to use the tool, but the context 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 the tool as read-only and non-destructive, so the description adds value by detailing the exact response behavior for two key scenarios: authenticated state with empty pending[], and missing credentials with connect_url and per-install URLs. This goes beyond the annotations and provides useful behavioral context, though it does not cover partial connection states.

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, with the main purpose stated first and conditional details following. Every sentence adds information without redundancy, making it 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?

For a tool with no parameters and safe read-only annotations, the description sufficiently covers return behavior for the main cases. There is no output schema, so the description's mention of 'authenticated:true', 'pending[]', 'connect_url', and 'per-install URLs' provides essential context. It could be slightly richer by explicitly describing partial connection states, but it remains adequate for the tool's complexity.

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 and full schema coverage, the input schema is trivially complete. The description does not need to explain parameters; the baseline for 0 params is 4, and no additional parameter semantics are required or missing.

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 a specific verb and resource. It distinguishes itself from siblings like 'authenticate' by focusing on status reporting rather than authentication actions, and the two conditional outcomes (providers connected vs missing credentials) further clarify its purpose.

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 this tool (to check connection status and get URLs) by describing its outputs, but it does not explicitly state when not to use it or name alternative tools. The usage context is clear but without exclusions, meriting a mid-range score.

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 (readOnlyHint: false, openWorldHint: true) are consistent with the description's disclosure of write behavior. The description adds significant value beyond the annotations by revealing that invoke runs a tool one-off even when not installed, that paid tools may return a checkout link requiring retry, and that writes require ownership/admin. This is exactly the kind of non-obvious behavioral context an agent needs.

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 comprehensive with no fluff, covering the entire API surface in a single dense paragraph. It could be slightly better structured with paragraph breaks or bullet points for readability, but every sentence communicates important information about flows, actions, or caveats.

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 tool with 23 parameters and no output schema, the description does an excellent job covering the core flows, auth, billing, permissions, and the prompt library distinction. The few gaps include no mention of the resume parameter, no explanation of what output the describe/search return beyond 'installed_in_toolkit vs installed_in_workspace' flags, and limited context around search_prompts vs the main flow. These feel like minor omissions relative to the tool's overall complexity.

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?

While schema coverage is 0% (the description must do all the work), it successfully explains the key parameters including action (search/describe/install/invoke), mcp_id/tool_id/arguments for the invoke flow, and the prompt_* fields for the prompt library. However, several parameters remain unexplained for the primary marketplace flow (resume, conversation, limit, request_name) which prevents a perfect 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 what the tool does: it's the official mcp.ai marketplace/catalog of MCPs and the way to run them, with a concrete core flow (search → describe → invoke). It effectively distinguishes itself from siblings by being the platform-level marketplace while siblings like authenticate, portal_transparencia_peti_consultar, and report_bug are specific tools within the ecosystem.

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: 'prefer invoke for a single/occasional use' vs. 'Use install only to make an MCP PERMANENT', which directly addresses selection between alternatives. It also covers edge cases like requiring connect links for credentials, checkout links for empty wallets, and specifies that writes require workspace owner/admin.

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 (readOnly, idempotent, not destructive), the description discloses payment model (prepaid credit), legal responsibility (LGPD), data classification (not confidential), and hosting details. This meaningfully adds behavioral context that annotations don't cover, such as cost implications and compliance 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 a single dense paragraph with mixed content: tool purpose, payment, legal disclaimers, and data governance. While all points are relevant, it could be more structured and front-loaded with the core function, making it less scannable than ideal.

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 one-parameter query tool with strong annotations, the description covers the essentials: what, where, cost, and legal framing. The lack of output schema and simple input mean the risk of missing critical information is low, and it adequately equips an agent to decide on 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?

With 0% schema description coverage, the description should compensate for the undocumented 'cpf' parameter, but it never mentions CPF or explains what input is needed. The parameter name is self-explanatory to a Brazilian audience, but the description misses the opportunity to clarify purpose, format, or constraints.

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's a consultation tool for the Child Labor Eradication Program (PETI) on the Transparency Portal, with a specific verb ('consultar') and resource. It distinguishes itself from generic siblings like 'authenticate' or 'marketplace' by naming the official database, though it could be more explicit about the exact data fields queried.

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?

Implied usage context is present: pay-per-query, no platform credentials needed, and legitimacy under LGPD. However, it doesn't explicitly state when to use this tool versus alternatives or provide exclusion criteria, which is partially mitigated by the fact that siblings are unrelated platform 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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the requirement to include the conversation array for reproduction, which is useful behavior context, but it does not disclose other details such as rate limits, response time, or what occurs after reporting.

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 with no unnecessary words. It front-loads the purpose and provides a key usage detail about the conversation array. Every sentence 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?

This is a simple tool with no output schema, and annotations cover the safety aspects. The description covers purpose, usage, and the important reproduction detail. It could benefit from explaining what happens after submission or potential limitations, but given the tool's simplicity, 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?

Schema description coverage is 0%, so the description must compensate for missing parameter explanations. It explicitly explains the conversation parameter and implies that message contains the feedback text, but the context parameter remains undefined. This partially compensates for the schema gap but not entirely.

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.' It uses specific verbs and a defined scope. Sibling tools such as authenticate, connect, or marketplace are unrelated, so this tool is distinct.

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 it (bug reports, missing features, feedback) and even instructs to include the conversation array. It does not explicitly mention when not to use it or name alternatives, but no sibling tool competes with this function.

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, covering the safety profile. The description adds no new behavioral traits beyond restating that it 'shows' versions, which aligns with the annotations. It doesn't mention return value format or any side effects, but the annotations lower the bar. Score 3 is appropriate as minimal added value.

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 front-loads the action ('Show') and the target ('current MCP platform and adapter versions'). It contains no filler, making it optimally sized for its content.

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, read-only), the description is nearly complete. It states exactly what is displayed, and the lack of output details is acceptable because no schema exists and the operation is trivial. The only gap is a note about format or timing, but that's minor.

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, so schema coverage is trivially 100%. With no parameters, the description has no obligation to explain themادات. The tool's behavior is fully determined by the description, which is sufficient.

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 verb ('Show') and the resource ('current MCP platform and adapter versions'), making the tool's purpose unambiguous. It distinguishes from sibling tools like connect or authenticate, though it doesn't explicitly differentiate from toolkit_info, which might also report 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?

There is no guidance on when to use this tool versus alternatives. The description is purely declarative and provides no context about typical use cases (e.g., debugging, session initialization) or exclusions. For a tool with no parameters and a simple read operation, some hint about its role would help.

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