DNIT: Infrações

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

The description goes beyond annotations by explaining the authentication flow: browser login, token copying, and configuration options. It discloses that calling with no args returns a link (no side effect) and calling with token establishes a session, which is consistent with idempotentHint=true. It adds meaningful context about the two behaviors 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 informative but somewhat lengthy, with a run-on style. However, it is well-structured with 'Best:' and 'Or' to delineate options, and front-loads the core action (log in, copy token). It could be tightened but remains focused and readable.

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 (one optional parameter, no output schema), the description covers the essential usage scenarios adequately. It explains both invocation modes and the permanent/session distinction, which is sufficient for an agent to decide how to call it. Minor gap: it doesn't describe the response (e.g., success message), but it's not critical.

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 token parameter is fully explained: it is the JWT copied from the browser, used for session-only login, and can be omitted to get the link. Since schema coverage is 0%, the description effectively compensates by defining the parameter's purpose and optionality, making it clear for the agent.

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: to authenticate the user with MCP.AI by obtaining an access token via browser login. It specifies the exact action (log in, copy token) and the two distinct modes (permanent config vs. session-only). It is verb-specific and differentiates from sibling tools like 'connect' through its focus 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?

The description provides explicit guidance on when to use each mode: calling with no args to get the login link, or with a token for session login. It also gives a best-practice recommendation for permanent connection (config header). While it doesn't explicitly contrast with 'connect', the context is clear and actionable.

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, so the description doesn't need to restate those. It adds valuable behavioral context: it returns different structures depending on state (authenticated:true and empty pending[] vs. connect_url and per-install URLs). This goes beyond the annotations and helps the agent anticipate the response variety.

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 and gets straight to the point. The first sentence states the purpose, and the second explains the two common states. Every sentence earns its place; no fluff or redundancy. It is well-structured and front-loaded.

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 the tool has no parameters and no output schema, the description is complete enough: it explains what the tool does and the key conditional behaviors. The only minor omission is not mentioning the return format for URLs or any other potential states, but for a status-check tool with no complexity, this is sufficient. Sibling tools like 'authenticate' and 'marketplace' are not referenced, but that is not required for 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 tool has zero parameters, and the schema description coverage is 100% (i.e., no parameters to document). The description adds value by explaining what the tool returns in different scenarios, which is the main semantic content an agent needs. The baseline for 0 params is 4, and the description does not need to compensate for any missing parameter docs.

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: 'Returns connection status and URLs.' It specifies the verb 'returns' and the resource 'connection status and URLs', and distinguishes it from sibling tools like 'authenticate' by focusing on status rather than performing authentication. The details about 'authenticated:true' and 'pending[]' further clarify what it provides.

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 about when to use this tool: when checking connection status, especially 'When all providers are connected' or 'When credentials are missing'. It does not explicitly name alternative tools or state when not to use it, but it implies that for actually authenticating, one would use 'authenticate'. This is a minor gap; a note about not using it to establish connections would make it 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 the tool read-only, idempotent, and non-destructive. The description adds valuable operational context beyond that: it is hosted by the platform but requires no platform credentials, it is paid via prepaid credit, and it exposes non-confidential official data with LGPD controller responsibilities. This goes beyond the annotations and helps the agent understand side effects (cost) and access 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 compact and front-loaded with the core purpose, then provides contextual details about hosting, payment, data source, and LGPD in a few short clauses. It avoids redundancy and is appropriately sized, though the legal compliance sentence is somewhat boilerplate. Every part contributes useful information for an agent considering the tool.

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 covers business and legal context (payment model, official data, data controller), it does not explain how to invoke the tool correctly: parameter semantics, authentication flow (whether login_senha or pkcs12_cert is required in practice), or what the response looks like (no output schema). The tool has moderate complexity with six parameters and no output schema, so the description is insufficient for correct 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 input schema has six parameters with zero descriptions, and the tool description does not explain any of them. The agent is left to infer the meaning of placa, renavam, login_cpf, login_senha, pkcs12_cert, and pkcs12_pass solely from their names. Critical details like parameter formats, required vs optional authentication fields, and how the certificate/password are used are completely absent, which is a severe gap for a tool with this many 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 function: consulting DNIT infractions from an official source. The phrasing 'DNIT: Infrações, consulta em fonte oficial' conveys a specific verb ('consulta') and resource ('Infrações'), and it is obviously distinct from the generic sibling tools like authenticate or connect. The purpose is unambiguous and well-scoped.

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 that this is a pay-per-query service from official Brazilian sources, with no platform credentials required, and that the client is accountable for LGPD compliance. This helps an agent decide when to use it, though it does not explicitly exclude alternative tools. Since the sibling tools are unrelated system tools, the context is sufficient to guide selection.

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 substantial behavioral detail beyond the annotations: invoke runs one-off without installing or bloating the toolkit, credential needs yield a connect link, empty wallet yields checkout/top-up, and install/uninstall/subscribe/cancel require workspace owner/admin. It also explains installed_in_toolkit versus installed_in_workspace flags. No contradictions with 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 long but information-dense and front-loaded, opening with the tool's identity and then covering the core flow, edge behaviors, permissions, and secondary prompt-library capabilities. Each sentence adds actionable detail rather than padding.

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 large action surface, no output schema, and sparse annotations, the description covers the main flows, return-link behaviors, permissions, and how the prompt library differs. It provides enough context for an agent to choose the right action and parameters for most marketplace requests.

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 and 23 parameters, the description carries the burden and largely compensates by explaining the action enum and key parameter meanings: action=search, describe returns full profile with tool ids and params, invoke takes tool_id and arguments, and prompt actions involve prompt_vars. It does not explicitly walk through every parameter, but it adds significant operational meaning.

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 mcp.ai marketplace and the way to discover, describe, and run MCPs. It names the core verbs and resources (search, describe, invoke, install, prompt library) and distinguishes those capabilities from sibling tools like report_bug and toolkit_info.

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?

It gives explicit when-to-use guidance: invoke for one-off use versus install for permanent toolkit membership, prefer invoke when the MCP is not installed, use list_tools for what is callable now, and use request_mcp when nothing fits. It also explains the intended flow: search -> describe -> pick tool_id -> invoke.

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 the tool is non-destructive and idempotent. The description adds context by explaining that the conversation array is included for reproduction purposes, which is useful, but it does not disclose other behavioral details such as data handling, response behavior, or side effects beyond what annotations provide.

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 and front-loads the core purpose. Every sentence provides necessary information with no wasted words.

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 tool with three parameters and no output schema, the description covers the primary purpose and one key parameter. However, parameter semantics are incomplete, and the description does not fully compensate for the lack of schema descriptions, so it is adequate but not rich.

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 meaning. It partially explains the conversation parameter as a 'conversation array', but it does not clarify that the schema types it as a string, nor does it explain the 'context' parameter or the expected format of the message.

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: report a bug, missing feature, or send feedback. It uses a specific verb and resource, and it is distinct from sibling tools 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 provides clear context for when to use the tool: whenever the user wants to report a bug, request a missing feature, or give feedback. It does not explicitly mention when not to use it or name alternatives, but the intended use cases are evident.

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, which covers the safety profile. The description adds the context that versions are 'current' and specifically of the MCP platform and adapter, 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?

The description is one short, front-loaded sentence every word earns its place. It immediately communicates the action and object without any filler.

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, no output schema, and a simple read-only purpose, the description is complete. It tells the agent exactly what to expect (current MCP platform and adapter versions) and no further explanation is necessary.

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 baseline is 4 per the rubric. The description needs to explain no parameter semantics, and indeed it doesn't need to since there is nothing to configure.

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 a clear resource ('current MCP platform and adapter versions'). This clearly distinguishes it from siblings like authenticate, connect, and report_bug.

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 on when to use this tool versus alternatives such as toolkit_info. The intended use (e.g., checking versions for debugging) is only implied but not stated.

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, idempotentHint, and destructiveHint. The description complements this by detailing the output, without contradicting the read-only nature.

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 packs all relevant information without fluff 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?

Given there is no output schema, the description sufficiently specifies what the tool returns, including a breakdown of the toolkit state, making it complete for its purpose.

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, so the description does not need to explain any. With 100% schema coverage (zero params), the baseline is 3, but the description effectively conveys the tool's behavior without missing 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?

The description clearly states the tool's function: returns the current toolkit state with specific details (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from sibling tools like authenticate, connect, etc.

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?

It is implicit that this tool is used to inspect the toolkit's current state, given its read-only nature. However, it does not explicitly mention when to use it over alternatives, but the purpose is clear enough.

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