DNIT: Infrações (CNPJ)

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

The description discloses important behavioral details beyond annotations: it explains that the session can be temporary or permanent via config, that tokens are JWT-based, and that calling with no arguments returns a login link. This complements the annotations (readOnlyHint false, idempotentHint true) 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 compact and front-loaded, covering usage modes, token format, config header, and session-only login in a few sentences. The phrase 'MCP.AI for IDE agents (Cursor, etc.)' is slightly opaque, but every sentence contributes useful information with minimal 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 one-optional-parameter, no-output-schema tool, the description is largely complete: it tells the agent how to invoke both modes and what to expect (link vs. token submission). It does not mention failure/error behavior or what the tool returns after a token is accepted, but this is not a major gap for an authentication helper.

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 only exposes an optional, undocumented 'token' property, so the description carries the full semantic burden. It explicitly explains the token parameter with `{ token: "<jwt>" }` and differentiates the no-argument call that yields the login link. This is meaningful and compensates for the 0% schema description 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 identifies the tool's purpose: logging in IDE agents via a browser, obtaining or passing an access token, and establishing a connection. It goes beyond the bare name by explaining both the login link flow and the token submission flow, distinguishing the tool from vague 'connect' or 'marketplace' siblings.

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 contexts: use no args to get the login link, use a token for session-only login, and prefer server-config header for a permanent connection. It does not explicitly state when not to use this tool or name alternatives among siblings, but the conditional guidance is clear enough.

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 establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral detail beyond these annotations: it describes what the tool returns in different connection states and that it supplies connect_url when credentials are missing. No contradiction 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 very compact: two sentences, with the primary purpose in the first sentence and behavioral details in the second. Every sentence adds value without redundancy or 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 zero-parameter, read-only status tool with no output schema, the description covers both normal and incomplete-credential scenarios and identifies the relevant returned data (authenticated, pending[], connect_url, per-install URLs). This is complete enough for correct tool selection and 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 tool has zero parameters, so the parameter semantics burden is minimal. The description fully replaces any need for parameter explanation, and the schema contains no properties requiring further clarification.

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', making it easy to identify the tool's function. It distinguishes itself from sibling 'authenticate' by focusing on status/URL discovery rather than performing 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 clear context for when this tool is useful, including distinct behavior for connected vs missing-credential states. It lacks an explicit 'do not use' or alternative recommendation, but the conditional returned data communicates when to use it.

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, idempotentHint, destructiveHint), the description adds behavioral context: payment via prepaid credit, no platform credentials needed, data is non-confidential official information, and the client is data controller under LGPD. It does not contradict the annotations and enriches the agent's understanding of side effects and obligations.

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, compact sentence that front-loads the purpose ('DNIT: Infrações (CNPJ), consulta em fonte oficial') before providing payment, data, and legal context. Every phrase earns its place; no filler or repetition. It's slightly dense but efficient for the information conveyed.

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?

With six parameters and no output schema, the description should explain more about expected input and return. It covers purpose, cost, data sensitivity, and legal compliance, but omits how to use the authentication-related parameters and what exactly the response contains (beyond 'infrações'). The ambiguity around credentials (platform vs. official source) further reduces completeness. It's adequate for a simple read query but not fully comprehensive.

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 bears full responsibility for explaining parameters. It fails to do so. The required 'cnpj' and 'razao_social' are self-evident from the tool's purpose, but the optional login_cpf, login_senha, pkcs12_cert, and pkcs12_pass are unexplained. The mention of 'sem credenciais da plataforma' confuses rather than clarifies, as these credentials presumably belong to the official source. No parameter meaning is added beyond their names.

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 query for DNIT infractions (CNPJ) from an official source ('DNIT: Infrações (CNPJ), consulta em fonte oficial'). It uses a specific verb ('consulta') and resource, distinguishing it from the generic sibling tools (authenticate, connect, etc.). A slight deduction for not explicitly stating that it retrieves a list of infractions for the given CNPJ, but the intent is 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 contextual usage hints: it's hosted by the platform, requires prepaid credit per query, and accesses official Brazilian sources available to citizens. It clarifies the data is not confidential and notes LGPD responsibility. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions (e.g., when not to use). Given the niche scope, the context is sufficient but not comprehensive.

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 only provide flags (readOnlyHint=false, openWorldHint=true), so the description carries the transparency burden — and it delivers. It discloses that invoke runs uninstalled MCPs one-off without toolkit bloat, returns a connect link on missing credentials and a checkout/top-up link on empty wallet with retry semantics, requires workspace owner/admin for writes, and flags installed_in_toolkit vs installed_in_workspace. 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?

At roughly 300 words, it is long, but the tool is a 14-action, 23-parameter router, so the density is largely justified. It is well-structured: identity and core flow first, then the KEY invoke exception, install vs invoke guidance, peripheral actions, permission note, and finally the prompt-library section. Nearly every sentence carries information; minor fat like the 'consulta um CPF' example could be trimmed.

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 multi-action tool with no output schema, the description covers the main flows thoroughly: discovery, profile contents (tools with id/params/pricing/auth), invoke edge cases (not-installed, credentials, payment), permission requirements, billing actions, and the prompt library. Gaps remain around return/response shapes and a few secondary parameters, but given the 14-action complexity this is strong coverage.

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 coverage, the description must compensate, and it largely does: it narrates the action enum (search/describe/invoke/install/list_tools/subscribe/cancel/report_bug/request_mcp and the three prompt actions), explains tool_id ('so you pick the right tool_id'), prompt_vars ('{{variables}} filled'), and prompt_slug (shareable mcp.ai/p/<slug> link). However, several params remain unexplained (conversation, immediate, tier_slug, prompt_targets, prompt_category, message), 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 opens with a precise identity — 'the in-platform catalog of every MCP/tool, AND the way to run them' — establishing a specific resource and the verbs (search, describe, invoke, install). It enumerates the core flow and explicitly separates the MCP catalog from the prompt library, and its scope clearly differentiates it from sibling tools like connect and authenticate.

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' vs. '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 prescribes retry behavior after connect/checkout links and distinguishes the prompt-library actions from MCP actions. This is textbook usage 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?

The description adds the contextual detail that the conversation array is for 'reproduction,' which implies the tool forwards issue data. However, it does not disclose what happens after reporting (e.g., creates a ticket, sends an email) or any side effects. Annotations (idempotentHint: true, destructiveHint: false) are not contradicted, but the description adds minimal behavioral insight beyond those.

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?

Two concise sentences that front-load the core purpose and include a critical usage note. No filler words or redundancy; every part contributes to understanding 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?

For a tool with three string parameters, no output schema, and straightforward semantics, the description sufficiently covers the essential usage. It could mention the absence of a return value or confirmation behavior, but the simplicity of the tool makes such omissions non-critical. The key insight about conversation history is included.

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 coverage, the description must elaborate on parameters. It does explain the 'conversation' parameter's purpose ('for reproduction') and implies the 'message' parameter via context, but it leaves 'context' undefined and does not cover all parameters equally. This partial enhancement moves it above the absolute baseline but does not fully compensate for the schema's silence.

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 clear verb ('Report') and resource ('bug, missing feature, or send feedback'), making the tool's purpose immediately obvious. It distinguishes itself from sibling tools (e.g., 'authenticate', 'show_version') by explicitly stating its domain. The instruction to include recent messages further clarifies its role.

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 provided about when to use the tool versus alternatives, and no exclusion criteria or when-not-to-use scenarios are mentioned. The description only gives a usage tip (include conversation), leaving the agent to infer the appropriate context from the tool name and purpose.

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 is consistent with the readOnly and non-destructive annotations but adds no additional behavioral details beyond what the annotations already convey. It does not contradict them but also provides no extra 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 a single, concise sentence with no unnecessary words or repetition. It gets straight to the point.

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 adequately explains the tool's purpose and the output (versions), which is sufficient for a simple version-check tool. However, it could specify the output format or structure, but this 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 no parameters, so schema coverage is effectively 100%. The description doesn't need to explain parameters, and it doesn't, which is acceptable 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 function: showing the current MCP platform and adapter versions. It is specific and distinct 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 simply states its function without any contextual information about appropriate scenarios.

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 behavioral context by disclosing the specific content of the return value (installed MCPs, connection status, accounts, catalog tools), which is beyond what annotations provide. It does not contradict any annotation.

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 sentence that front-loads the action ('Returns the current toolkit state') and efficiently enumerates the contained elements without fluff. Every word contributes to understanding, with no repetition of schema or annotation 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 read-only, no-parameter info tool with no output schema, the description fully and self-sufficiently explains what the tool returns. It lists all key components of the state (installed MCPs, connection status, accounts, catalog tool counts), making it complete for an agent to decide whether to invoke it and 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 the schema is empty (100% coverage vacuously). Per the rubric, a description with 0 parameters receives a baseline of 4 since there is nothing to compensate for. The description correctly avoids adding parameter-related 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?

The description states the specific verb 'Returns' and the resource 'current toolkit state', then enumerates exactly what that includes: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly differentiates it from sibling tools like authenticate or connect, which perform actions rather than report state.

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 checking the toolkit's overall integration status by listing the state information it provides, but it does not explicitly state when to prefer this over siblings like show_version or provide any 'when-not-to-use' guidance. The context is clear but no alternatives or exclusions are mentioned.

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