SEFAZ RR: NFC-e

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

The description adds transparency beyond the annotations by explaining the persistence of the header connection ('permanent, non-expiring') versus session-only token login. It also describes the behavior of getting a link with no args. This enriches the provided hints 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 concise and information-dense, using two sentences to cover configuration, session login, and no-arg behavior. While it reads as a run-on, each clause adds unique value. Slight restructuring into steps could improve scannability, but it remains efficient.

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 one optional parameter and no output schema, the description covers the essential workflow and edge cases (no args, token supplied). It doesn't mention return values, but in the absence of an output schema, that is not strictly required. The tool is simple enough that the description feels 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 provides no description for the token parameter, but the description fully explains it: a JWT pasted by the user, and that omitting it yields a login link. This completely compensates for the 0% schema coverage, giving the agent all necessary 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 states the tool's purpose: authenticating IDE agents (e.g., Cursor) via login flow. It specifies the resource and the action (obtaining an access token) and differentiates itself from siblings like connect or marketplace, which are unrelated. The scope is precise.

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 instructions: call with no args to get a link, or with a token for session-only login. It also contrasts two methods (persistent header vs. session token). However, it doesn't explicitly state when to choose this tool over alternatives or when not to use it, so it falls just short of a 5.

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 valuable context by describing response specifics: returns authenticated:true and empty pending[] when all providers are connected, and connect_url plus per-install URLs when credentials are missing. This goes beyond the safety hints and helps the agent anticipate output variations without an output schema.

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, front-loaded with the core purpose ('Returns connection status and URLs'), then provides conditional specifics. Every word is necessary, no fluff 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 tool with no output schema, the description fully explains the two primary response states and the URLs returned. It gives the agent enough to understand what to expect and how to interpret the result. Given the simplicity, this is 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 input schema has zero parameters, so the description correctly omits parameter details. Per the rubric, a baseline of 4 applies for tools with no parameters. Since there are no parameters to clarify, the description adds no parameter semantics but does not need to.

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 verbs ('returns') and resource ('connection status and URLs'). It distinguishes itself from siblings like authenticate (which handles authentication) and show_version (version info) by focusing solely on connection status and URL retrieval.

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 does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or complementary tools. While the purpose is clear, an agent might infer it is for checking connectivity before authentication, but there is no explicit guidance on when to prefer it over authenticate or other 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?

The description discloses important behavioral traits beyond annotations: invoke runs tools without installing them, one-off installs behind invoke require owner/admin, credential gaps return connect links, payment gaps return checkout links, and writes require workspace owner/admin. 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 dense but well-organized around the core flow, key invoke behavior, install vs invoke, and secondary functions. It is long, but nearly every sentence adds needed context for a multi-action tool; a few bullet points or short headings would improve scannability.

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, no output schema, and many actions, the description is remarkably complete: it covers discovery, running, installation, auth, billing, feedback, and prompt library actions. It could still better describe return shapes for search and list_tools, but the core behavior is well covered.

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 there are 23 parameters, so the description must carry the burden. It explains the meaning of the action field and several key parameters (tool_id, prompt_vars, prompt_slug), but many parameters like immediate, tier_slug, conversation, cancel_reason, and prompt_targets remain unexplained.

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 catalog and execution layer, with a specific core flow (search → describe → invoke). It distinguishes itself from siblings by covering catalog discovery, one-off invocation, installation, billing, and prompt-library actions in one tool.

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: prefer invoke for single/occasional use, use install only for permanent additions, list_tools for what is callable now, report_bug/request_mcp for feedback/new MCPs. It even explains retry behavior when credentials or payment are needed.

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 include idempotentHint=true, destructiveHint=false, readOnlyHint=false, openWorldHint=false. The description doesn't contradict annotations. It adds that the tool includes conversation for reproduction, but it doesn't disclose details like what happens after submission (e.g., confirmation, rate limits). Given the annotations cover safety (idempotent, non-destructive), a 3 is appropriate—some context added, 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 a single, compact sentence that conveys purpose and a key usage detail. It is front-loaded and wastes no 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?

The tool is straightforward (reporting feedback), with no output schema and simple parameters. Annotations cover idempotency and non-destructiveness. The description is sufficient for basic use but could be improved by clarifying what 'context' might contain and the expected format for 'conversation' (e.g., JSON array string). It's a minimal but adequate description for a 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 schema has three parameters: message (required, string), context (string, default ''), conversation (string, default '[]'). Schema description coverage is 0%, so the description must compensate. The description mentions 'conversation array' and implies its purpose (for reproduction), but it doesn't explain 'message' or 'context' beyond the schema. Given low coverage, the description adds some value for 'conversation' but leaves 'message' and 'context' semantically thin.

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: reporting a bug, missing feature, or feedback, and it mentions including the conversation array for reproduction. It distinguishes from siblings like 'show_version' or 'toolkit_info' which are informational, and 'sefaz_rr_nfce_consultar' which is a specific external query. However, it doesn't explicitly name alternative tools for feedback, so it's clear but not fully differentiated.

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 this tool (when reporting a bug/missing feature/feedback) and gives a key guideline about including the conversation array. It doesn't mention when not to use it or suggest alternative tools for other purposes, but the context is fairly clear for a feedback tool.

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 valuable context beyond these: that it is hosted without platform credentials, requires prepaid credits per query, and that data is public and non-confidential. It also clarifies data controller responsibilities under LGPD. This enhances transparency without contradicting 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, compact sentence that front-loads the tool's purpose and includes essential operational details (payment, LGPD) without redundancy. It is concise and each clause adds value, though the density might reduce 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?

For a simple read-only tool with annotations covering safety, the description provides sufficient context about official sources, payment, and legal compliance. However, it omits the meaning of the sole parameter and does not mention return format or error behavior, leaving minor gaps. Given the absence of an output schema, some return description could be expected, but the core 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 has one required parameter 'nfce' with no description, and schema description coverage is 0%. The tool description fails to explain what the 'nfce' parameter represents (likely the NFC-e access key or number), leaving the agent to infer from the tool name. This is a significant gap for a single-parameter tool.

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 performs a query ('consulta') of NFC-e documents from the official SEFAZ RR source, specifying the resource and action. It distinguishes from sibling tools like authenticate or connect, which serve 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 description implies usage for consulting official Brazilian public data (NFC-e) and mentions payment and LGPD compliance, but it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. The context is clear but lacks explicit guidance on selection among similar 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, which already convey the safe, non-destructive nature. The description adds that it shows versions, but it doesn't disclose additional behavioral aspects like whether it requires authentication or affects state, which are not necessary given the simplicity. With high annotation coverage, a score of 3 is 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 concise sentence that is front-loaded and states exactly what the tool does. There is no waste or unnecessary detail, making it highly efficient.

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 (0 params, no output schema), the description is complete enough. It covers the essential purpose and the tool has no complex behavior. The annotations provide additional safety context. Slight lack of detail on the format of the version output, but for a simple query tool, this is acceptable.

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 is fully covered (100% coverage). The description effectively explains what the tool does, and there's no additional parameter semantics needed. Baseline for 0 params is 4, which fits 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's purpose: to show the current MCP platform and adapter versions. It is specific with a verb and resource (show versions), and while siblings like 'toolkit_info' or 'connect' may implicitly relate, the description clearly distinguishes by focusing on version display.

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 a clear context (when to use: to show version info) but does not explicitly state when not to use it or mention alternatives. Since it's a simple query tool with no parameters, usage is straightforward, though no explicit exclusions or alternative references are provided.

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 mark the tool as readOnly, idempotent, and non-destructive; the description adds useful behavioral context by specifying what state it reports: installed MCPs, connection status, accounts, and catalog tool counts. This goes beyond the structured 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, front-loaded sentence that immediately states the tool's purpose and then lists the returned details with a colon. Every word contributes useful information with no 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 the low complexity of a no-parameter read-only status tool and the absence of an output schema, the description fully covers what the agent needs to know: the exact categories of information returned. It is complete for selection and invocation.

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 an empty schema, so there is no parameter documentation burden. The description appropriately focuses on return content rather than parameters, matching the baseline for parameterless tools.

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' with a clear resource ('current toolkit state') and enumerates the exact contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This scope clearly distinguishes it from 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?

The description implies the tool is used to inspect overall toolkit status, but it does not explicitly state when to prefer it over alternatives such as show_version, nor does it mention any exclusions. It provides clear context but no alternative guidance.

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