DETRAN AL: Infrações

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

Annotations declare idempotentHint=true but not readOnlyHint, which implies mutation. The description adds that it triggers a browser login flow ('log in in the browser') and returns a link when called with no args, and that token login is 'session-only' vs 'permanent' via config. It does not state what the response looks like (link or success message), but the annotation set is minimal and the description covers the key behavioral contexts (login process, persistence).

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 sentences, but packed with essential guidance. The first sentence establishes purpose and audience. The second sentence explains the two usage modes with explicit call syntax. Slightly dense but no fluff; could be split into bullets, but it's efficient for an auth tool that needs to convey both browser flow and API usage.

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 login tool with 1 optional param, the description covers the core flow: browser login, token capture, config vs session options, and empty-call behavior. Missing details: what the response contains when returning the link, timeout behavior, or error handling, but given the low complexity and no output schema, this is adequate for an agent to initiate authentication. The 'permanent, non-expiring' note is a helpful extra.

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 has 1 optional parameter 'token' with 0% description coverage. The description explains the token's meaning ('<jwt>' pasted from browser) and its role in session vs permanent login. It explicitly says 'or with no args to get the link', which clarifies the optional nature. This adds meaning beyond the bare schema, though it doesn't detail token format beyond '<jwt>'.

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?

Purpose is clearly stated as 'log in' for MCP.AI, but the description actually says the tool's purpose is 'MCP.AI for IDE agents (Cursor, etc.). The description states it 'authenticate' is a clear verb+resource ('authenticate' with a 'for IDE agents' audience qualifier, plus 'token' parameter and 'no args to get the link'). The target audience 'IDE agents (Cursor, etc.)' distinguishes it from sibling tools like 'connect' or 'marketplace' which imply different resources.

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 provides two usage paths: 'add it to this server's config as a header... for a permanent, non-expiring connection' vs 'paste it here for a session-only login'. States the exact call patterns: 'call with { token: "<jwt>" }' or 'with no args to get the link'. Sibling tools are not mentioned, but the tool's role in the auth flow is clearly differentiated by the config vs session distinction.

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 mark it as read-only, idempotent, and non-destructive. The description adds valuable behavioral detail: it specifies exactly what returns in different states (authenticated:true with empty pending[] vs connect_url for toolkit and per-install URLs). This goes beyond annotations and helps predict output.

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 sentences, fully front-loaded with the main purpose, and each sentence provides necessary detail without fluff. Efficient and clear.

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 is complete for a zero-parameter tool with no output schema. It explains the two possible return scenarios, including the authenticated state and the missing-credentials state, which covers the main use cases. No further details seem 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 there is nothing to explain. According to the rubric, a zero-parameter tool gets a baseline of 4; the description doesn't need to elaborate on 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?

Description clearly states the tool returns connection status and URLs, with specific output variations based on provider connection state. This distinguishes it from siblings like authenticate (which presumably initiates auth) and show_version (which shows version info), as it is focused on connectivity.

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: use this to check connection status and get URLs when credentials are missing. It doesn't explicitly mention when not to use it or compare with alternatives, but the purpose is obvious enough that an agent would know when to call 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: payment model (prepaid credit), lack of platform credentials, the official/non-confidential nature of the data, and LGPD responsibility for the client. This goes beyond the annotations by explaining operational and legal aspects.

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 compact 4-sentence paragraph, front-loaded with the main purpose and followed by relevant operational and legal context. Each sentence earns its place, covering the query, hosting, payment, data source, and LGPD without unnecessary verbosity.

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 provides good context about the source, payment, and legal aspects, but it does not describe what the query returns (e.g., a list of violations with details). With no output schema present, the description should clarify return values, but it remains implicit. This is a notable gap for a complete understanding 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?

Schema description coverage is 0%, so the description must compensate for parameter semantics. The description does not mention 'placa' or 'renavam' at all, providing no additional meaning beyond the schema. The parameter names are somewhat self-explanatory in the Brazilian context, but the description adds zero value for parameter understanding.

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: 'DETRAN AL: Infrações, consulta em fonte oficial' – querying traffic violations from the official DETRAN AL source. The verb 'consultar' and resource 'infrações' are specific, and the tool is clearly distinguished from sibling tools (authenticate, connect, etc.) which are generic platform operations.

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 usage context: it is hosted by the platform, requires no platform credentials, and is paid per query with prepaid credit. It also clarifies that the data source is the same as available to citizens, which implies when it should be used. No explicit alternatives are mentioned, but no domain-specific alternatives exist among the sibling 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?

The description adds substantial behavior beyond annotations. It discloses that 'invoke works even when the MCP is NOT installed' and runs a 'one-off' without bloating the toolkit, details credential/payment edge cases ('invoke returns a connect link' / 'checkout/top-up link'), and states that writes require 'workspace owner/admin.' This supplements readOnlyHint=false with critical operational expectations.

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 dense but front-loaded block that opens with a clear one-sentence summary. It packs a lot of essential information without filler, though it could be improved with structured bullets or section headers for readability. No sentence is wasted.

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 14 action values, 23 parameters, billing/auth concerns, and a separate prompt library, the description is remarkably complete. It covers the core flow, exception handling, permission requirements, one-off vs permanent install differences, and all major action categories. The only gap is parameter-level detail, but the high-level guidance is sufficient for an agent to invoke the tool 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?

The schema has 23 parameters with 0% description coverage. The description explains the core `action` parameter values and the high-level workflow, including how tool_id is selected and how prompt_vars are 'filled' for get_prompt. However, it does not describe many other parameters such as `limit`, `immediate`, `tier_slug`, `cancel_reason`, `prompt_category`, etc., so the added meaning is partial rather than comprehensive.

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 in-platform catalog of every MCP/tool, AND the way to run them.' It enumerates specific actions (search, describe, invoke, install, subscribe) and distinguishes the prompt library as a separate facet. This establishes a precise scope and differentiates it from sibling tools like toolkit_info 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?

It provides an explicit core flow: 'action=search discovers MCPs by intent → describe returns one MCP's full profile... → invoke RUNS that tool.' It also gives clear when-to-use guidance, including 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT.' It differentiates list_tools ('lists what is callable right now') and request_mcp ('when nothing fits'), offering clear alternatives.

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 convey the safety profile (not read-only, not destructive, idempotent). The description adds useful guidance by instructing to include the conversation array for reproduction, which implies the report will be used for debugging. However, it does not disclose what happens after submission (e.g., where the report goes, expected response), and it does not explain the idempotent hint, so some behavioral ambiguity remains.

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, front-loaded sentence that states the purpose and immediately gives the key usage instruction. Every word earns its place, and there is no wasted verbiage.

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 is simple with three string parameters and no output schema. The description covers the purpose and one parameter (conversation) but omits details about the 'message' and 'context' parameters, and it misrepresents the conversation field as an array rather than a JSON string. This is adequate but not fully complete for an agent to invoke it correctly without additional assumptions.

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 by explaining parameters. It explicitly mentions 'conversation array' and indirectly alludes to 'message' via 'send feedback,' but the 'context' parameter is entirely unexplained. Moreover, it calls 'conversation' an array while the schema expects a string, which could mislead users. This leaves significant gaps in parameter understanding.

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.' The verb 'report' and direct listing of report types distinguish it from sibling tools like authenticate or show_version, making its role immediately understood.

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 the tool: any time the user needs to submit a bug report, feature request, or general feedback. It does not explicitly mention alternatives or exclusions, but the context is unambiguous and no other sibling tool serves the feedback 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying exactly what information is shown (platform and adapter versions), which is useful context beyond the annotations. It fully discloses the behavior without contradiction.

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, clear sentence that conveys the entire purpose without any fluff. It is front-loaded and every word earns its place. Perfectly concise for a simple 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 trivial read-only version tool with no parameters, no output schema, and comprehensive annotations, the description is complete. It tells the agent what the tool does (shows versions) and nothing else is needed. The description is fully adequate for the tool's 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, and schema coverage is 100%. The description does not need to explain parameter meanings since there are none. The baseline of 4 applies because the description adds no parameter information, but none is needed.

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 exactly what the tool does: 'Show the current MCP platform and adapter versions.' The verb 'show' is specific, the resource (platform and adapter versions) is clear, and it is distinct from siblings like authenticate or connect which have 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 provides no explicit guidance on when to use this tool versus alternatives. Given the simplicity and the sibling 'toolkit_info' which might also provide version-related information, the description does not clarify the differentiation or when not to use it. The usage context is 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about the output composition (installed MCPs, status, accounts, tool counts) but does not provide extras like auth needs, rate limits, or error conditions. This is adequate given the bar is lower with annotations present.

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, front-loaded sentence that efficiently enumerates exactly what the tool returns, with no filler or redundant wording. Every clause provides value, and the structure is clean.

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 zero-parameter tool with no output schema, the description covers all relevant aspects: it states the purpose and the four types of information returned. It does not specify exact output format or potential edge cases (e.g., empty list of MCPs), but given the simplicity and annotations, 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?

The tool has zero parameters, so there is nothing to describe. Schema description coverage is 100% trivially. Since no parameters exist, the baseline score of 4 applies; the description appropriately focuses on the output rather than parametric details.

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 identifies the resource ('current toolkit state') with four concrete components: installed MCPs, connection status, connected accounts, and number of catalog tools. This fully distinguishes the tool from siblings like 'connect' or 'authenticate' which are action-oriented, and 'show_version' which targets only a version.

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 implicitly indicates when to use the tool (to inspect toolkit state) but does not explicitly contrast with alternatives. While sibling 'show_version' might also be a read-only info tool, there is no explicit guidance on choosing between them or when not to use this tool. The context is clear but lacks stated exclusions or alternative mentions.

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