SENATRAN: Infrações

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

Annotations already indicate idempotent and non-destructive behavior. The description adds context about token being a JWT, the non-expiring vs session-only distinction, and the two modes (with/without token). It does not contradict annotations, and the additional detail on side effects (e.g., what happens if token is invalid) is omitted but not critical given the idempotency.

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 long, with the first sentence front-loading the purpose. The second sentence is long but necessary to explain the two usage paths. No fluff, though it could be split for 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, the description covers the main input and behavior well: the token parameter, the two invocation modes, and the result (link or login). It lacks explicit mention of return values or error handling, but for an auth tool with low complexity, this is adequate.

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 description must compensate. It explains the 'token' parameter as a JWT, marks it optional, and specifies how it is used ('call with { token: ... }' vs no args). This provides clear meaning beyond the raw 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 specifies the tool's purpose: authentication for IDE agents via browser login and token retrieval. It distinguishes itself from sibling tools like 'connect' by explicitly stating it handles login and token exchange, making the action 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?

Provides explicit when-to-use scenarios: permanent connection via config header vs session-only via token paste, and when to call with token vs no args. It also names the alternative ('add to config') and gives step-by-step usage, making the choice clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by detailing the output shape in different states (authenticated:true with empty pending[] vs connect_url and per-install URLs), going beyond the safety profile.

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, front-loaded with the core purpose, and every sentence adds meaningful behavioral detail. 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 parameterless tool with no output schema, the description explains the main return values and conditional outcomes well. The annotations further clarify safety and idempotency, making the tool sufficiently complete for an agent.

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 parameter semantics are trivially covered. Baseline for 0 params is 4; the description adds no parameter info 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 clearly states the tool returns connection status and URLs, with specific behavior for connected vs missing-credential scenarios. This distinguishes it from sibling authenticate, which is an action tool, while this is a status check.

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 it (to check connection status or get URLs when credentials are missing) but does not explicitly name alternatives or exclusions (e.g., 'use authenticate instead'). The conditional scenarios provide clear usage context.

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 discloses important behavioral traits beyond annotations: invoke runs the MCP one-off without installing it, credential/checkout failures return follow-up links, writes require owner/admin, and prompt library links open without login. No contradiction with the annotations is 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 long but structured: it opens with a clear definition, then explains the core flow, key invoke behavior, install vs invoke distinction, billing/report/request actions, and prompt library in sequence. It could be tightened, but the length is justified by the tool's breadth.

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 highly complete for the main search/describe/invoke workflow, auth requirements, billing flows, and prompt library. However, it omits the 'resume' action present in the schema and does not cover all action-specific parameters, so there are still notable gaps for a 14-action dispatcher.

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 carries a heavy burden. It explains the core action/mcp_id/tool_id flow and gives some semantics for prompt and billing operations, but many parameters (tier_slug, immediate, prompt_targets, conversation, report_context, etc.) are left without meaning 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 states a clear, specific purpose: it is the marketplace catalog for MCPs/tools and the execution path for running them. It also differentiates the tool from sibling tools by covering the full search → describe → invoke flow, billing actions, prompt library, and MCP request/report actions.

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 one-off use, use install for permanent toolkit membership, use request_mcp when nothing fits, and separates prompt library usage from MCP usage. It also states permission requirements for writes (owner/admin), which helps the agent decide when to proceed.

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 provide idempotentHint and destructiveHint, but the description adds no further transparency about side effects, authentication needs, or post-action outcomes. The tool's behavior after reporting (e.g., ticket creation, email) is not disclosed.

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 extraneous information. It is well-structured and directly conveys the core action.

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 three parameters and lack of output schema, the description leaves the overall usage context incomplete. It does not explain how the parameters interplay or what constitutes a valid report, making it insufficient for a user to fully understand the tool's operation.

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?

Only the 'conversation' parameter is vaguely hinted as 'conversation array' for reproduction, but the schema defines it as a string, creating confusion. The 'context' and 'message' parameters are entirely unexplained, leaving their semantic roles unclear.

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.' This is specific and unambiguous, and it distinguishes the tool from the unrelated sibling tools listed.

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 offers minimal usage guidance. It mentions including the conversation array for reproduction, but does not specify when to use this tool over alternatives or provide any conditional context. No explicit usage instructions are given.

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, the description adds meaningful behavioral context: the tool is billed by prepaid credits, requires no platform credentials, handles non-confidential public data, and assigns LGPD compliance responsibilities to the caller. These details are useful and do not contradict the readOnly/idempotent 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 relatively brief, but it has some redundancy: 'consulta em fonte oficial' title and later 'consulta informação de fontes e órgãos oficiais' repeat the same idea. Still, it is well-structured with multiple useful statements in a compact story.

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 annotation covers safety, and the description adds legal and billing context, but with 8 parameters and no output schema, an agent would need more instruction on how to invoke it (e.g., plate required, date ranges, login fields). It is not complete enough for fully confident calling in the absence of other clues.

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 does not explain any parameter. It doesn't even mention the required 'placa' input, nor the optional login/date/certificate fields, leaving the agent to infer semantics from the field names alone.

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 action (consulta de infrações) and the resource (SENATRAN), stating it queries official Brazilian traffic infraction data. It is specific and distinguishes itself from generic sibling tools like authenticate and 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 gives useful usage context: no platform credentials are needed, queries are pay-per-use via prepaid credits, and it uses official public data. It does not explicitly compare to alternatives, but no similar data query siblings exist, so the intended usage is reasonably clear.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate those. It adds minimal value by specifying 'current' versions, which implies a read-only query. No additional behavioral details (e.g., network calls, authentication requirements) are provided, but given the annotations, the description is consistent and sufficient 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, concise sentence that conveys exactly what the tool does without any fluff. It is front-loaded and every word earns its place. No redundancy or unnecessary details are present.

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, parameterless tool with no output schema, the description is complete enough. It states the purpose clearly, and the annotations cover safety and idempotency. It could mention what the output looks like (e.g., a string with version numbers), but that is minor given the tool's simplicity. Overall, it provides sufficient context for an agent to use it appropriately.

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 description coverage is 100% (vacuously). Per the rubric, a baseline of 4 is appropriate when there are no parameters. The description adds no parameter-specific meaning, but none is needed since there are none to document.

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 show current MCP platform and adapter versions. It uses a specific verb ('show') and resource ('platform and adapter versions'), which distinguishes it from sibling tools like 'toolkit_info' that might provide broader information. The purpose is unambiguous and directly tied to the tool name.

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 tells what the tool does but gives no explicit guidance on when to use it versus alternatives. It lacks any context like 'use this to check version compatibility' or exclusions. While the simplicity implies it's for obtaining version info, there is no stated scenario or alternative comparison, making it merely adequate.

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 correctly aligns with the annotations (readOnlyHint: true, idempotentHint: true), consistently describing a non-mutating operation. It adds value by revealing what kind of state is returned, such as connection status and account associations, which is contextual information not fully captured by the structured annotations alone.

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-constructed sentence that front-loads the key verb 'Returns' and then uses a colon to efficiently enumerate the components of the returned state. There is no wasted wording, and every element adds informational value.

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 info tool with no parameters, no output schema, and safe annotations, the description is completely sufficient. It details exactly what information the agent can expect to receive (MCPs, statuses, accounts, tool counts), making it complete for its simple, non-destructive 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?

The tool has zero parameters, and the schema coverage is 100%, meaning there are no parameter ambiguities to resolve. The description successfully communicates the data the agent will receive, effectively compensating for the lack of parameters by explaining the output structure.

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 highly specific verb ('Returns') and resource ('current toolkit state'), and breaks down exactly what that state entails: installed MCPs, connection status, connected accounts, and catalog tool counts. This clarity makes its purpose distinct from the action-oriented siblings 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?

It provides clear context for use by specifying the exact nature of the return value (state inspection). While it doesn't explicitly name alternatives or exclusions to other tools like 'show_version', the described purpose is so specific that an agent would easily recognize when to use this for state inspection versus performing actions.

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