Prefeitura RJ Rio de Janeiro: NFS-e (Nota Fiscal Eletrônica de Serviços)

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds useful context beyond this: the token is a JWT, no-args returns the login link, the config-header approach is permanent and non-expiring, and pasting a token gives session-only authentication. This does not contradict any annotation.

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, each carrying distinct information: the browser login context, the permanent config-header option, and the session-token call shape. It is slightly wordy but well structured with 'Best' and 'Or', and avoids 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?

Given one optional parameter and no output schema, the description covers both authentication flows, the JWT format, and the no-args link retrieval. It does not explicitly describe the return value for the token-call path, but it is reasonably complete for an auth tool with minimal 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?

The schema only lists an optional string token with no description (0% coverage). The description compensates by explaining the token type ('<jwt>'), that it should be passed after the user pastes it, and that omitting arguments retrieves the link. It could add error/validation behavior, but it covers the essential parameter semantics.

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 an authentication flow for MCP.AI IDE agents: log in, copy the access token, and either configure a permanent header or pass a session token. It includes concrete call modes, which is more specific than the generic name. It does not explicitly differentiate from the sibling 'connect' tool, but the auth context is 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?

The description gives explicit usage guidance: 'Best: add it to this server's config as a header...' for a permanent connection versus 'paste it here for a session-only login' with the exact call shape. It clearly explains when to call with a token and when to call with no args, but it does not state when not to use this tool or point to alternatives 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?

Annotations already declare the tool read-only, idempotent, and non-destructive, so the description adds behavior about the differing return shapes across connection states. It tells the agent what happens when credentials are missing versus when everything is connected, adding real transparency beyond 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 two sentences long, front-loaded with the core purpose, and every sentence adds meaningful behavioral detail. 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 zero-parameter, read-only status tool with no output schema, the description explains the return values in both relevant scenarios. It adequately covers the main cases an agent would encounter and is complete for this simple 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 has zero parameters, and the schema coverage is 100% by definition. The baseline for no-parameter tools is 4, and there is no parameter detail needed here.

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 also distinguishes itself from sibling tools like authenticate by focusing on status rather than initiating authentication.

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 expected outcomes in different states (all connected vs. missing credentials), which implies when the tool is useful for checking status. It does not explicitly mention alternatives like authenticate, but the conditional behavior provides enough practical 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?

Beyond the annotations (openWorldHint, non-readOnly, non-destructive), the description discloses key behavioral traits: invoke runs without installing, may return connect or checkout links requiring user action and retry, writes need owner/admin, and search/describe flag installation status. This adds context the annotations don't provide and contradicts nothing.

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 quite long (~300 words) but front-loaded with the core flow and key guidance. Each sentence conveys useful information, covering invoke vs install, auth, payment, prompt library, and permissions. While it could be tightened, the structure is logical and 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 23 parameters, 14 actions, no output schema, and limited annotations, the description is remarkably complete. It clarifies the intend-to-execution pipeline, runtime behaviors (links, retries), authorization requirements, and the separate prompt library subsystem. Agents can confidently use this tool without ambiguity.

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 the central 'action' enum and the core flow (search→describe→invoke), clarifying which parameters matter for each action (mcp_id, tool_id, arguments, etc.). It doesn't detail every parameter like limit or prompt_vars, but given the tool's many actions, it provides enough semantics for correct usage. A 4 is appropriate; a 5 would require per-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 clearly states the tool's purpose: it is the official mcp.ai marketplace catalog and execution platform. It explicitly names the core actions (search, describe, invoke, install) and distinguishes itself from siblings like authenticate or show_version. It also covers the prompt library aspect, leaving no ambiguity about scope.

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 guidance on when to use each action: prefer invoke for one-off runs (even without installation), use install only for permanent additions, list_tools for current callable tools, and subscribe/cancel for billing. It also explains when to use search_prompts/get_prompt for prompt text. This fully addresses selection between 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 readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: payment is required, data is from official sources and not confidential, and LGPD compliance responsibility lies with the client. This goes beyond the annotations without contradicting 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 a single dense paragraph with legal jargon (LGPD, data controller) that adds length without improving tool usability. It could be more streamlined while keeping the payment and source details. It's not overly long but lacks crisp front-loading.

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 4 parameters, no output schema, and no parameter descriptions, the description should compensate more. It covers payment, source, and legal aspects but omits return value expectations and parameter specifics, leaving gaps in 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?

Schema coverage is 0%, and the description provides no information about the parameters (numero_nota, codigo_verificacao, cpf, cnpj). The names hint at their purpose, but the description fails to explain formats, optionality, or relationships, leaving the agent without essential guidance.

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 consultation service for NFS-e (electronic service invoices) from Rio de Janeiro's city hall, using a specific verb ('consulta') and resource ('NFS-e'), which distinguishes it from unrelated siblings like authentication or marketplace 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 provides clear operational context: hosted by the platform, no platform credentials needed, and pay-per-query via prepaid credit. While it doesn't explicitly compare to alternatives, the siblings are unrelated, so this context suffices for basic usage 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 already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is partly covered. The description adds the reproduction context but does not disclose whether duplicate reports are possible, what backend side effects occur, or whether confirmation is returned. This is adequate but not rich.

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 short sentences, with the core purpose front-loaded and the actionable reproduction instruction placed second. Every sentence contributes useful information with 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?

The tool is simple with three string parameters and no output schema, so the description need not be extensive. However, it omits what should go in 'message' and 'context', which are not self-explanatory from the schema. The reproduction guidance is helpful, but the overall description is just barely sufficient.

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 all three parameters. It only clarifies 'conversation' by asking for recent messages for reproduction, while 'message' and 'context' are left unexplained beyond the tool's general purpose. This leaves significant semantic gaps for the agent.

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 with a specific verb and resource: 'Report a bug, missing feature, or send feedback.' This is distinct from the sibling tools, which cover authentication, connectivity, marketplace, and version info. The reproduction instruction further clarifies the intended function.

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 for when to use the tool—bug reporting, missing features, or general feedback. It also gives a concrete usage instruction: include the conversation array with recent messages for reproduction. It does not explicitly list exclusions or alternatives, but the purpose is specific enough that no close sibling competes for this behavior.

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 disclose readOnlyHint and idempotentHint, and the description aligns with these. No additional behavioral context (e.g., network access, caching) is provided beyond what annotations state, but given the low risk and annotation coverage, it meets the baseline with no contradictions.

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 is front-loaded with the action ('Show') and clearly states the resource. Every word adds value, with no fluff or repetition.

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 trivial complexity of a version-display tool, the description is sufficient. There is no output schema, but the return value is predictable for the agent. Annotations and the simple nature of the tool cover safety and idempotency, so nothing else 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, so the schema coverage is trivially 100%. The description correctly omits parameter details, and there is no missing semantic information. This aligns with the baseline of 4 for no 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?

The description uses a specific verb ('Show') and a precise resource ('current MCP platform and adapter versions'). It is unambiguous and immediately clear what the tool does, distinguishing it from siblings 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?

The description is self-explanatory for a version-information tool but does not explicitly mention when to prefer it over alternatives (e.g., 'toolkit_info'). There is no exclusion guidance or alternative tools named, but the simplicity of the tool makes the implied usage acceptable.

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 fully discloses what the tool returns (MCPs, connection status, accounts, catalog counts) and the annotations confirm it is read-only and idempotent. No side effects or unexpected behavior are hidden.

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, compact sentence that conveys all necessary information without redundancy. It is well-structured and easy to parse.

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 lists what is returned but does not specify the exact response format (e.g., JSON structure). However, since there is no output schema, this is acceptable. It provides enough context for an agent to understand the tool's purpose and output.

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 no parameters, and the schema coverage is 100% (since none exist). The description correctly avoids mentioning parameters, so there is nothing to clarify.

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 exactly states what the tool does: 'Returns the current toolkit state' and enumerates the specific details (installed MCPs, connection status, accounts, catalog tools). It clearly distinguishes from sibling tools like 'show_version' or 'authenticate' by focusing on toolkit-level introspection.

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 when you need to inspect the toolkit's MCP connections and accounts, but does not explicitly state 'use this when...'. It is clear enough for an agent to infer when to call it, though a more explicit conditional would be ideal.

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