Prefeitura MS Campo Grande: NFS-e (Nota Fiscal Eletrônica de Serviços)

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

Annotations declare idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description does not contradict these but adds some context about creating a permanent or session-only connection, which is helpful. However, it doesn't fully disclose side effects (e.g., what happens to existing tokens, rate limits, or how the token is stored), though the context is decent given 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?

Two sentences, front-loaded with the purpose and structured options. Every word contributes value, and the colon-guided list makes it easy to scan. No fluff.

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 parameter and no output schema, the description is complete enough to guide an agent. It covers the two main flows (with/without token) and the permanent vs session distinction. A small gap is that it doesn't mention what the response is, but that's not critical given the tool's simple nature and the absence of an output schema.

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. It explains that the 'token' parameter is the JWT to paste for session-only login, and that omitting it returns the login link. This adds meaning beyond the raw JSON schema, effectively documenting the single parameter.

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 'authenticate' is used to log in to MCP.AI for IDE agents, with a specific verb and resource. It distinguishes between two modes (permanent via config header vs session-only via token parameter), leaving no ambiguity.

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 on when to use it (first-time authentication) and offers two explicit options for the user, but it does not explicitly mention alternatives among the sibling tools (e.g., 'connect' or 'marketplace'), so there's no direct comparison. Still, it implicitly differentiates by stating the two authentication flows.

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 and idempotentHint, and the description adds meaningful behavioral details: the 'authenticated' boolean, the empty 'pending[]' array, and the conditional 'connect_url'. This goes beyond the annotations without contradicting them in any way.

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 tightly written sentences deliver the core purpose and key conditional behavior. Every word earns its place, and the structure front-loads the main 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?

For a simple status-checking tool, the description covers all essential behaviors: what it returns and how it differs under different states. No output schema means no missing return specifications; the description is complete for this context.

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 zero parameters and 100% schema coverage (vacuously), the description doesn't need to explain parameters. Per rubric, this is a baseline 4, and there's no missing information to penalize.

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 a specific verb and resource. It distinguishes itself by describing specific behavioral states, though it doesn't name sibling tools explicitly. The purpose is unmistakable and not a tautology.

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 clear context for use, explaining when the tool returns different results (all connected vs. missing credentials). It doesn't explicitly exclude any scenarios or name alternatives, but the intent is obvious. 'Clear context, no exclusions' fits perfectly.

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 goes far beyond annotations by detailing side effects: invoke runs one-off without installing, returns connect/checkout links for auth/payment, writes require owner/admin. It also notes search/describe flag installed status. No contradiction with readOnlyHint=false or destructiveHint=false—the write capabilities are transparently described. This is exceptional transparency for a complex 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?

The description is long, but every sentence adds value—it covers core flow, edge cases, permissions, and the prompt library without filler. It is front-loaded with the purpose and flows logically, though a structured list of actions could improve scannability. The density is justified by the tool's complexity, so a 4 is fair.

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 complexity (14 actions, 23 params, no output schema), the description is remarkably complete: it covers discovery, execution, billing, permissions, edge cases (auth/payment), and even the separate prompt library. It leaves little ambiguity about what the tool can do and how to approach it. This is a model of completeness for a multi-action 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 23 parameters and 0% schema coverage in the description, the description must compensate. It explains the meaning of 'action' values and the flow, giving semantic context. However, it does not describe individual parameters like limit, query, message, immediate, prompt_vars, etc. The description provides high-level action semantics but leaves parameter details to the schema. Since the schema has defaults and enums, a 4 is appropriate—strong but not exhaustive.

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 is the official mcp.ai marketplace catalog and runtime, with a specific verb (search/describe/invoke/install) and resource (MCPs and prompts). It distinguishes from siblings like authenticate/connect by describing its unique role as the central hub for discovering and running MCPs, plus the prompt library.

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 explicitly details the core flow (search → describe → invoke), when to use invoke vs install, and when to use subscribe/cancel/report_bug/request_mcp. It even explains when to prefer one action over another (e.g., 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT'). This is exemplary usage guidance with 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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful operational context beyond those: no platform credentials, prepaid credit cost, non-confidential official data, and LGPD data-controller responsibility. 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?

The description is reasonably compact and front-loads the core purpose, then adds authentication, billing, and compliance context. It is slightly dense but contains no significant 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?

The tool has four required parameters with no schema descriptions and no output schema. The description covers purpose, cost, authentication, and legal context, but omits parameter format guidance and expected response behavior, leaving the tool only minimally 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?

Schema description coverage is 0%, and the description does not explain cnpj_prestador, numero_nota, codigo_verificacao, or inscricao_municipal or their expected formats. The parameter names are somewhat self-explanatory, but the description adds no meaning beyond the 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 identifies the tool as a query/consulta for NFS-e from the official Campo Grande/MS municipal source, using a specific verb and resource. It also distinguishes it from unrelated sibling tools such as 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 gives useful usage context: official public data, no platform credentials required, prepaid per-query billing, and LGPD responsibility. It does not explicitly name alternatives or exclusion scenarios, but the sibling tools are unrelated, making the context sufficiently 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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is established. The description adds reproduction guidance, but it does not disclose side effects such as ticket creation, network submission, or response behavior beyond sending feedback.

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 short sentences: the first states the purpose, the second gives a concrete actionable instruction. There is no filler 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?

For a simple reporting tool with no output schema, the description provides core purpose and reproduction guidance. However, it leaves the required 'message' field and optional 'context' field unexplained, so an agent may need to infer their intended content.

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 only clarifies the conversation parameter with 'Include the conversation array.' It does not explain the required 'message' parameter, the optional 'context' parameter, or that conversation is actually a string-serialized array, not an array type.

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 'Report a bug, missing feature, or send feedback,' using a specific verb and naming the resource types. This clearly distinguishes the tool from sibling tools like authenticate, connect, and show_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 gives clear context for when to use the tool: bug reports, missing features, and feedback. It also instructs including the conversation array for reproduction, but does not explicitly state when not to use it or name alternatives, although the sibling tools seem unrelated.

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 specificity about what versions are shown (MCP platform and adapter) but does not describe output format or further behavior. This adds some value but not extensive context, matching a score of 3.

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 entire description is one concise, front-loaded sentence with zero wasted words. It directly states the action and scope, earning a perfect score.

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, no output schema, and a simple read-only action, the description adequately covers what the tool does. It specifies the exact information returned (MCP platform and adapter versions) and is sufficient for an agent to invoke it correctly. No additional context is needed.

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. With no parameters to explain, the description does not need to add parameter semantics. Baseline for 0 params is 4, as the description adds no parameter-specific value but is not deficient.

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 what the tool does: 'Show the current MCP platform and adapter versions.' It specifies the verb (show), the resource (MCP platform and adapter versions), and distinguishes it from sibling tools like authenticate or connect which have entirely 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 tool's purpose is self-evident and there are no obvious alternatives for querying versions among siblings, so no explicit when-to-use guidance is necessary. The description provides clear context (displaying versions) without exclusions, aligning with a score of 4.

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 contextual value beyond these annotations by specifying exactly what state is reported—installed MCPs, connection status, accounts, and catalog tool counts—which enriches the transactional profile of this read-only operation.

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 packs all relevant information into a single front-loaded sentence. It names the action ('Returns'), the resource ('toolkit state'), and the specific contents, with no filler or redundant 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?

With no output schema, the description correctly takes on the responsibility of explaining return values, listing installed MCPs, statuses, accounts, and tool counts. It could be more precise about connection status values, but for a zero-parameter informational tool with strong annotations, this level of detail 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?

The tool has zero parameters, which serves as a baseline of 4. The description correctly avoids describing nonexistent parameters, and the empty schema requires no additional explanation.

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 the specific verb 'Returns' and clearly identifies the resource (current toolkit state) along with a detailed scope: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly distinguishes it from action-oriented siblings like connect/authenticate and from show_version, which likely returns only version information.

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 frames when to use the tool: whenever a snapshot of the toolkit state and its integrations is needed. It does not explicitly state when not to use it or name alternatives, but the provided content scope makes the intended usage obvious and distinct from the listed siblings.

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