Prefeitura MG Contagem: NFS-e (Nota Fiscal Eletrônica de Serviços)

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

The description adds behavioral context beyond annotations by explaining the difference between permanent (header) and session-only (token passed) authentication, and that no args triggers a link response. Annotations already mark idempotent, which is consistent.

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 moderately sized with a clear front-loaded purpose, followed by two concrete usage options. Every sentence conveys useful information, though it could be slightly tighter.

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 covers the authentication flow comprehensively for a simple tool, including both permanent and session-based methods and the no-arg behavior. It omits output/error details, but no output schema exists and the tool's purpose is clear.

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 provides no description for the optional token parameter, but the description fully explains its semantics: calling with { token: "<jwt>" } after user pastes, or omitting it to receive the link. This compensates for the 0% schema 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 states the tool's function: login in the browser, copy the access token, and either configure a permanent header or provide a session token. It uses specific verbs and resources, making the purpose unmistakable.

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 explicitly describes two usage paths: adding the token as a permanent header in server config, or calling with a token for session-only login, and calling with no args to retrieve the login link. This gives the agent clear when-to-use 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?

Annotations (readOnlyHint: true, destructiveHint: false) already indicate a safe, read-only operation. The description adds concrete behavioral details: it returns authenticated:true and empty pending[] when all providers connected, and connect_url otherwise. This goes beyond annotations and clarifies the exact output states.

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, highly efficient. Clearly explains purpose and conditional behavior with 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?

Tool has no parameters and no output schema, but the description explains the two possible return states and what URLs are provided. That is sufficient for an agent to know what to expect. No gaps.

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 parametersached. With 0 parameters, baseline is 4. No additional parameter info 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's function: returns connection status and URLs. It specifies what it returns in different states (authenticated vs. pending), which distinguishes it from sibling tools like authenticate (which presumably performs authentication) and other status/utility tools.

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 by outlining what the response looks like under different conditions, but does not explicitly state when to use it versus alternatives like authenticate. It gives context about when credentials are missing, which indirectly guides usage, but lacks direct comparison to siblings.

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 indicate readOnlyHint=false, openWorldHint=true, so the description correctly implies operations can cause changes but also handles requests. It discloses behavioral traits beyond annotations: invoke works without install, one-off runs without bloating toolkit, returns connect link for credentials, checkout/top-up for payment, and writes require workspace owner/admin. This is rich context, though annotations already signal mutability, so a 4 seems appropriate.

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 dense paragraph packed with information, but it's well-structured with a clear flow from search to invoke, and covers alternative actions. It's front-loaded with the core purpose and then expands. Slightly long for one paragraph, but no repetition or fluff. A 4 seems right.

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 (23 params, no output schema), the description covers the essential flows, permissions, and special behaviors (invoke without install, payment/credential links, prompt library). It doesn't explain all parameters or the prompt library in depth, but given the constraints, it's fairly complete. Without output schema, it would be nice to mention return formats, but the description is substantial.

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 clarify parameters. It explains the 'action' enum values (search, describe, invoke, install, etc.) and mentions 'mcp_id', 'tool_id', 'arguments' in the flow, but doesn't detail many other params like prompt_* fields or limit. It adds meaning to key parameters but not all. With 0% schema coverage, the description compensates partially, so a conservative 3 is fair.

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 providing a catalog of every MCP/tool and the way to run them. It explicitly lists the core actions (search, describe, invoke) and expands on the two main use cases (discovery and execution). It differentiates from siblings by clarifying it's about the marketplace while other tools handle authentication or specific functionality.

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 guidance on when to use invoke vs install (prefer invoke for one-off use, install only for permanent additions) and explains the flow (search → describe → invoke). It also mentions when to use list_tools (what is callable right now) and alternatives like request_mcp for new builds. This is a strong 5, covering when-not as well.

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, destructiveHint), the description discloses additional behavioral traits such as the payment per query, the absence of platform credentials, and the non-confidential nature of the data. It also mentions LGPD compliance responsibilities, adding meaningful transparency.

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 paragraph but includes some redundancy, such as repeating the notion of official sources and mentioning similar details twice. It is not excessively long, but could be more concise while still delivering the key 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?

Given the annotations already provide basic flags, the description adds important context such as the official source, payment model, data sensitivity, and legal responsibility. It covers the essential operational and compliance aspects, though it omits parameter details, which is acceptable since the question focuses on overall completeness.

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 description does not explain any of the input parameters (declaracao, numero_nota, codigo_verificacao, cpf_cnpj_prestador). The schema provides no descriptions, and the text fails to add meaning or context for these fields, leaving parameter semantics entirely undocumented.

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: querying NFS-e (electronic service invoices) from the Contagem municipality in Minas Gerais, Brazil. It explicitly uses the verb 'consultar' and identifies the specific resource, distinguishing it from generic 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 some context about usage (e.g., prepaid credit, no platform credentials) but does not explicitly state when to use this tool versus alternatives. It lacks direct guidance on scenarios where this tool is preferred or when other tools should be used instead.

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 declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by specifying that the conversation array should be included for reproduction, which explains a behavioral requirement. It does not contradict annotations and provides context beyond 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 concise, two sentences, with the purpose front-loaded and a specific action instruction. No wasted words, and it covers both the what and a crucial how.

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 simplicity and existing annotations, the description is largely complete. It explains the core purpose and the key requirement for reproduction. It could optionally describe what happens after submission or the response format, but since no output schema exists, this is not strictly required. The lack of explanation for the 'context' parameter 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?

Schema description coverage is 0%, so the description must compensate. It clarifies the 'conversation' parameter's purpose (array for reproduction), but does not explain 'context' or the format/type of conversation as a JSON-encoded string. The required 'message' parameter is self-evident, but 'context' remains undocumented. This partial explanation places it at a baseline of 3.

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. It uses a specific verb ('report') and resource ('bug') and is clearly distinct from sibling tools like authenticate or connect. It also mentions the key usage instruction about including the conversation array.

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: when reporting issues or sending feedback. It provides a specific guidance to include the conversation array for reproduction, giving context. However, it does not explicitly exclude alternative tools or mention when not to use it, but given the sibling tools, none is an obvious alternative for this 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 agent knows this is safe. However, the description adds no extra behavioral context beyond the annotations—no mention of return format, authentication, or any side effects. Hence, it does not build on 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?

The description is a single, front-loaded sentence of 10 words, with no filler or repetition. Every word contributes to conveying the tool's core function.

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 simplicity (no params, no output schema) and the safety annotations, the description provides sufficient context to understand what the tool does. It omits details like return format or authentication prerequisites, but these are not critical for a version-checking 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?

The tool takes zero parameters, and the schema covers this completely. Since there are no parameters to document, the baseline of 4 applies, and the description does not need to add parameter 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 'Show' and clearly identifies the resource ('current MCP platform and adapter versions'), making the tool's purpose immediately clear and distinct from the authentication/mutation 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 implies the tool is for retrieving version information, but offers no explicit guidance on when to use it over alternatives (e.g., toolkit_info) or any exclusions. The usage context is vague but not misleading.

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, and the description aligns with these. It adds useful behavioral context beyond the annotations by specifying the exact scope of state returned (installed MCPs, connection status, accounts, and tool counts), which helps the agent understand the tool's read-only nature and output scope.

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 is tightly worded and front-loaded with the key verb ('Returns') and object ('current toolkit state'). The enumeration of returned content adds value without unnecessary elaboration.

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 introspection tool with good annotations, the description is largely sufficient. It explains the return content even though no output schema exists, but it does not elaborate on possible connection status values or the representation of accounts, which would enhance completeness.

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 baseline is 4. There is no parameter ambiguity to resolve, and the description appropriately focuses on behavior rather than parameters 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 uses a specific verb ('Returns') and clearly identifies the resource ('current toolkit state'), enumerating exactly what is included: installed MCPs, connection status, connected accounts, and catalog tool counts. It distinguishes itself from siblings like show_version and connect by focusing on broader toolkit state rather than version or connection 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?

There is no explicit guidance on when to use this tool versus alternatives such as connect, authenticate, or show_version. The description implies it is for inspecting state, but it does not state exclusions, prerequisites, or preferred contexts.

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