Pedágios: Pedágio Digital

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

Annotations only provide readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=false, which lack context. The description compensates well by explaining behavior: a session-only login, a permanent connection variant via config, and the flow of acquiring and using a token. This goes beyond the sparse annotation data.

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 packs in a lot of useful information, but it does so in long, run-on sentences with parenthetical asides and semicolons. While every word adds value, a more structured format with bullet points or clearer sentence boundaries would improve readability.

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 no output schema, no enums, and a single optional parameter, the description leaves nothing critical uncovered. It explains the full auth flow, the two login modes, the config alternative, and the no-args behavior. It is sufficient for an agent to invoke the tool successfully.

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%, so the description fully bears the responsibility of explaining the token parameter. It clarifies that token is a JWT string, when to pass it (session-only login), and when to omit it (to get the link). This compensates for the bare 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 uses a specific verb+resource: 'log in in the browser, copy the access token' and clearly explains the authentication flow. It distinguishes this from siblings by focusing solely on the auth handshake and explicitly covers all call signatures (no args, with 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 usage context by explaining the flow: call with no args to get a link, paste token back. However, it does not explicitly state when to use this tool versus the sibling tools like connect or marketplace, and there are no exclusions or alternatives mentioned.

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, covering the safety profile. The description adds valuable behavioral context beyond this: it explains the conditional response for 'all providers connected' (authenticated:true, empty pending[]) and for missing credentials (connect_url and per-install URLs). This gives the agent a clear expectation of what the tool returns in different 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, front-loaded with the main purpose ('Returns connection status and URLs'), and every sentence adds needed detail about conditional behavior. No wasted words 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?

For a zero-parameter, read-only status tool with no output schema, the description covers the two main scenarios (connected and missing credentials) sufficiently for an agent to select and understand the tool. No critical information is missing.

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 the schema is empty (coverage 100%). The description doesn't need to explain parameters, and the baseline for 0 params is 4. No further detail is required.

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 clearly states it 'Returns connection status and URLs' with specific detail about return states (authenticated:true vs connect_url). This distinguishes it from sibling tools like authenticate, which would initiate an auth flow. No 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 description provides clear context for checking connection status (returns status and URLs). It doesn't explicitly name alternatives or say 'use this when checking connection', but the read-only status-check nature is self-evident from the description and annotations. No exclusions are needed.

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, disclosing that invoke runs uninstalled MCPs one-off without bloating the tool list, that auth-gated tools return a connect link, that paid tools with empty wallets return a checkout/top-up link, and that writes require workspace owner/admin. It also explains the prompt library's shareable no-login links, adding substantial behavioral context.

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 dense and well-organized: it front-loads the core purpose, then uses a clear flow, a KEY callout, and distinct sections for install vs invoke, permissions, and the prompt library. It is not overly verbose for the number of actions it covers, though bullet formatting could have improved scannability.

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 parameters, no output schema), the description is quite complete: it explains the main flow, return-link behaviors, permission requirements, and prompt-library functions. It does not describe every action (e.g., resume) or all parameter semantics, and return shapes for non-core actions are mostly absent, leaving some gaps for an agent to infer.

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 carries the burden and does a strong job explaining the action parameter and the roles of mcp_id, tool_id, and arguments through the search/describe/invoke flow. However, many parameters (limit, immediate, tier_slug, conversation, prompt_targets, cancel_reason, etc.) are not explicitly explained, so the compensation is good but not complete.

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: the catalog of MCPs/tools and the way to run them. It enumerates the core flow (search → describe → invoke) and distinguishes itself from sibling tools like authenticate and connect by owning catalog discovery, one-off execution, installation, billing, and prompt-library 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?

The description gives explicit usage guidance: prefer invoke for single/occasional use, use install only for permanent toolkit membership, use list_tools to see what is callable now, and use request_mcp when nothing fits. It also explains when invoke returns connect or checkout links and that retry is needed after the user acts, which is actionable and 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?

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds behavioral details such as no credentials being required, payment through prepaid credit, and LGPD data-control obligations. It aligns with the read-only/idempotent hints and adds useful operational context, though it does not fully describe response or error 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 compact and informative: purpose, hosting/payment, data source, and LGPD responsibility are each covered in short clauses. Every part contributes useful detail, though the sequencing of 'Hospedado pela plataforma' after the initial purpose could be slightly clearer.

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 read-only tool, the description covers purpose, access, cost, and data privacy constraints. However, since there is no output schema, the lack of any mention of what the consultation returns is a meaningful gap. The description is minimally viable but not fully 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% and the description never mentions the 'placa' parameter. It does not clarify plate format, validation, or examples. The parameter name itself is reasonably self-documenting, but the description fails to compensate for the absence of schema-level parameter information.

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 states the tool performs a 'consulta' (query) of 'Pedágio Digital' using an official source, and further explains it fetches information from official Brazilian agencies available to citizens. This distinguishes it from the generic sibling tools (authenticate, connect, marketplace, etc.), though it does not explicitly describe exactly which toll-related data gets returned.

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 clear context: the tool is hosted by the platform, requires no platform credentials, and costs prepaid credit per query. It also clarifies the data is non-confidential and official, which helps an agent know when the tool is appropriate. It stops short of explicitly pointing to alternatives or when-not-to-use, but the sibling list contains no similar query 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 indicate idempotentHint=true and destructiveHint=false, and the description adds that this is for reporting bugs/feedback, which implies a non-mutating, safe operation. It also mentions including recent messages, which is a behavioral detail. No contradiction with annotations found.

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 and front-loaded: two sentences, no redundant information. It states the purpose and a key usage instruction, achieving maximum efficiency.

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 simple purpose and no output schema, so the description is mostly complete. It explains the core action and the conversation parameter. However, it does not clarify what 'message' should contain beyond the general purpose, and 'context' is undefined, but this is minor 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?

Schema description coverage is 0%, so the description must compensate. It explains the purpose of the 'conversation' parameter by instructing to include the conversation array, and implies 'message' is the feedback content. The 'context' parameter is not explained, but the description adds some value beyond the 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: 'Report a bug, missing feature, or send feedback.' It specifies the verb 'report' and the resource (bug/feature/feedback), distinguishing it from sibling tools like 'marketplace' or 'toolkit_info'. The addition of 'Include the conversation array with recent messages' clarifies the expected use case.

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 clear context for when to use the tool: to report bugs, missing features, or send feedback. It does not explicitly mention alternative tools, but the purpose is distinct enough from siblings. It also provides instructions on what to include (conversation array), which serves as a usage guideline.

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 the specific scope ('platform and adapter versions'), which complements the annotations well without contradicting them. Additional behavioral detail is unnecessary for such a trivial operation.

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?

Exactly one sentence, no filler, front-loads the verb and object. Every word contributes to 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 a parameterless, read-only tool with no output schema, the description adequately states what it shows. The lack of an output schema means the agent may not know the exact return format, but 'versions' implies a standard string or structure, acceptable for this 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 assured by both the schema (empty properties) and the description. No parameter documentation is needed; the baseline for 0 params is 4, and the description adds no unnecessary detail.

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 clearly names the resource: 'current MCP platform and adapter versions'. It distinguishes from siblings like 'authenticate' and 'connect' by focusing on version display, a distinct diagnostic 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 purpose inherently communicates when to use it: when version information about the MCP platform or adapters is needed. While it does not explicitly state exclusions or alternatives, the context of sibling tools makes its usage obvious as a diagnostic query rather than an action-oriented 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 declare readOnlyHint, idempotentHint, and destructiveHint, so safety is clear. The description adds valuable context by enumerating what state is returned (MCPs, statuses, accounts, catalog counts), going beyond what the empty input schema provides. No contradictions detected.

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 front-loads the core action and then lists the returned information. Every clause earns its place with no filler, redundancy, or unnecessary 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 no-parameter, read-only state tool, the description fully explains the return contents: installed MCPs, connection status, connected accounts, and catalog tool counts. It does not need to explain return values further, and no output schema is required to fill 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?

There are zero parameters, so the description cannot add parameter-level meaning beyond the empty schema. The baseline for zero-parameter tools applies, and the description appropriately focuses on the output rather than nonexistent inputs.

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's action ('Returns the current toolkit state') and specifies the exact resource and scope: installed MCPs, connection status, connected accounts, and catalog tool counts. This is specific enough to distinguish it from sibling tools like show_version 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 implies usage is for inspecting toolkit state but does not explicitly state when to use it versus alternatives like show_version or connect. It gives clear context about what information is returned but no exclusions or alternative references.

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