SEFAZ MS: IPVA

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

Annotations already indicate idempotent and non-destructive. The description adds context about permanent (header) vs session-only (paste) modes and that calling with no args returns a link. It does not detail all internal side effects but enough for an agent.

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?

Three sentences, clearly structured with 'Best' and 'Or' alternatives. Slightly verbose with the IDE context but each sentence adds 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 simple auth tool with one optional param and no output schema, the description covers the core flows: permanent config, session-only token, and obtaining the link. It lacks explicit return format but is largely 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 schema has one optional 'token' with no description. The description explains the token is a JWT and gives the exact call pattern: { token: '<jwt>' } or no args to obtain the link.

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 authenticates to MCP.AI, with specific verb 'log in' and resource 'MCP.AI', distinguishing it from sibling tools like 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?

It provides concrete usage scenarios: best practice for permanent config vs session-only login, and explains when to pass a token or no args. It does not explicitly compare to 'connect' but gives sufficient 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context about response variations (authenticated:true vs connect_url) but does not explain side effects or deeper behavior beyond that. It does not contradict annotations, so no 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 concise and front-loaded with the primary action and resource. It uses two sentences to convey the main behavior and conditional outcomes, with zero waste.

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 no parameters and an empty schema, the description covers the essential information about return values and conditions. It lacks some details like the exact structure of connect_url or per-install URLs, but given the simplicity, it is largely 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?

There are no parameters, and schema coverage is 100%. The description adds meaning by explaining the output semantics based on connection state, which is valuable beyond the empty schema. A baseline of 4 is appropriate.

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 details about the 'authenticated' and 'pending' fields. While it doesn't explicitly distinguish from siblings like 'authenticate' or 'toolkit_info', the action verb 'returns' and resource (connection status) are clear.

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 implies usage for checking connection status and provides scenarios (all connected vs. missing credentials), but it does not explicitly state when to use this tool over siblings like 'authenticate' or 'toolkit_info'. No exclusions or alternatives are 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?

Even though the annotation surface is minimal (readOnlyHint=false, openWorldHint=true), the description discloses rich behavior beyond it: summary of execution and behavior, we can see invoke works for non-installed MCPs without adding to the toolkit/bloating tool list, that connect/checkout links are returned for auth/payment needs, that permanently installs behind the scenes will happen in the installer, and that installed_in_toolkit vs installed_in_workspace is indicated at search/describe level. This is novel and highly useful context that annotations cannot express.

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 every sentence carries the message: main flow, the KEY invoke behavior, permission guards, and the prompt library distinction are all present. It is front-loaded with the core identity and separated by meaningful connectives ("Core flow", "KEY"), avoiding filler; the length is justified by the tool's keeper of 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?

For a 23-parameter multi-strategy tool with no output schema, the description provides a coherent model of almost all return behaviors (invoke returns connect/checkout links, publish_prompt returns a shareable link) and side-effect contexts (for "bloat" the toolkit, owner/admin requirements, one-off install behind invoke). It is missing a few parameter semantics and some list_tools/describe returns, but overall the agent receives a genuinely complete decision framework for invoking this 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?

With 0% schema-documentation coverage, the description does substantial compensatory work: it explains the semantic universe of the action enum (search, describe, install, invoke, subscribe/cancel, report_bug, request_mcp, ...), plus the meaning of prompt_* parameters (prompt_vars filled with {{variables}}, publish_prompt returns a shareable mcp.ai/p/<slug> link). Some parameters like topic/tier_slug, immediate, conversation, cancel_comment, and request_details are still left without explanation, so scope is slightly incomplete for a 23-parameter 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 defines the tool as "the official mcp.ai marketplace" that catalogs and runs MCPs, and it states the exact core flow: search → describe → invoke. It also distinguishes the marketplace's scope (catalog + prompt library) from sibling tools like authenticate, connect, and report_bug, leaving no ambiguity about what the tool does.

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" and "Use install only to make an MCP PERMANENT in the active toolkit." It also delineates the sub-actions (list_tools, subscribe/cancel, report_bug, request_mcp) and notes workspace owner/admin permission requirements for writes, which helps the agent choose correctly.

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 non-read-only but non-destructive behavior. The description adds useful context by instructing users to include conversation data for reproduction, which is behavioral guidance beyond the annotations. While it doesn't mention rate limits or auth, the simple nature of this tool and the presence of annotations lower the bar, and the description adds value.

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 front-loads the purpose and includes a direct instruction in the second part. Every word earns its place; no fluff or redundancy. This is a model of efficient writing.

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 no output schema, three flat parameters, and one required field, the description is mostly sufficient. It explains the key invocation detail (include conversation array). It loses a point for not clarifying what the 'message' parameter is for, especially since it's the only required parameter, but overall the tool is simple enough that 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?

With 0% schema description coverage, the description must compensate by explaining parameters. It only addresses the 'conversation' parameter explicitly, leaving 'message' and 'context' unexplained. Since it covers only one of three parameters and adds no details on format or required fields, it falls short of the need. A score of 2 reflects the partial but insufficient compensation.

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 ('Report') and clearly identifies the resource ('a bug, missing feature, or send feedback'). It also provides an important scoping detail (include conversation array) that distinguishes it from sibling tools like 'show_version' or 'authenticate'. This is exactly what a purpose statement should do.

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 makes it clear when to use the tool (when reporting a bug, missing feature, or feedback) and even gives a concrete instruction on what to include (conversation array). However, it does not explicitly name alternatives or exclusions, though siblings are unrelated. It slightly misses the 'alternatives named' bar, so a 4 is appropriate.

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 (read-only, idempotent, non-destructive), the description adds that the tool is hosted by the platform, requires prepaid credit per query, and clarifies that data is not confidential, shifting LGPD responsibility to the client.

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 succinct, front-loading the purpose and then providing necessary legal and payment context. It avoids unnecessary detail, though the legal phrasing could be more direct.

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 read-only query with three parameters and no output schema, the description covers the source, payment, and compliance aspects. However, it omits parameter explanations and any guidance on expected results or errors, leaving gaps for a fully informed call.

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 0% description coverage, and the tool description does not explain any of the three parameters (placa, renavam, numero_parcela). The agent receives no added meaning beyond the parameter names themselves.

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 as consulting IPVA from an official source (SEFAZ MS). The verb 'consulta' matches the tool name, and it is distinct from sibling tools, which are platform utilities 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 provides context: it is for querying IPVA from official Brazilian sources, with a payment model and LGPD compliance. It does not explicitly list alternatives or exclusions, but the sibling tool names make the use case 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, idempotentHint=true, and destructiveHint=false, so the description need not restate these. The description adds minimal behavioral context beyond the annotations, but it is consistent and mentions the specific version types (platform and adapter). This meets the baseline but does not provide extra behavioral details.

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 directly states the tool's function. Every word earns its place, with no 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 zero-parameter read-only tool with no output schema, the description fully covers what the tool does. The absence of output schema information is acceptable since the tool simply reports versions, and the description is complete for its intended 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% (vacuously). Per the rubric, a baseline of 4 is appropriate since there are no parameters to describe, and the description does not need to compensate for any gaps.

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 'Show the current MCP platform and adapter versions' uses a specific verb ('Show') and identifies the exact resource ('MCP platform and adapter versions'). It clearly distinguishes the tool's function from its siblings, which are unrelated actions 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 clearly implies this is for retrieving version information, with no alternatives or exclusions. While it doesn't explicitly mention when not to use it, the simplicity of the tool makes usage obvious and the context is 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 carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing exactly what state is surfaced (which MCPs, their statuses, connected accounts, tool counts), going beyond the annotation booleans. Slight knock for not covering edge behavior (e.g., what happens with zero MCPs), but strong for an info tool.

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?

One sentence, front-loaded with the verb "Returns", with a scannable colon-enumerated list of the state facets. Every word earns its place — zero fluff with good information density.

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 inspection tool with strong annotations and no output schema, the description covers all essentials: the resource, the four enumerated state facets, and nothing extraneous. Consistent with the get_calls calibration for complete simple tools.

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?

Zero parameters, so the description has nothing to clarify there. The schema covers 100% of parameters vacuously, and the description appropriately spends no words on nonexistent parameters. Baseline 4 for zero-param tools applies.

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?

"Returns the current toolkit state" uses a specific verb+resource, and the enumeration of what's included (installed MCPs, connection status, accounts, catalog tool counts) crisply distinguishes it from siblings like connect, authenticate, and show_version. The scope 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 usage is implied through words like "current" and "status" — the agent can infer this is for state inspection rather than mutation — but there's no explicit when-to-use guidance, exclusion criteria, or named alternatives (e.g., using connect for establishing connections). Functional but not explicit.

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