SEFAZ RO: NFC-e Completa

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

Discloses side effects: permanent connection via config modification, session-only via paste. Idempotent annotation (true) aligns with description's mention of repeated token use. Does not contradict annotations, but could explicitly state that calling with no args returns a link (already implied).

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 slightly verbose but well-structured with 'Best:' and 'Or' sections. It conveys all necessary information without redundancy, though could be tightened.

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?

Covers the authentication process, parameter usage, and outcomes (permanent vs session). Missing explicit return value description, but the mention of 'get the link' hints at the response. Overall complete for a simple authentication 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 token parameter is explained: it's a JWT that the user pastes, and it's optional since passing no args retrieves the link. This compensates for the lack of schema description, though it doesn't detail the token's format beyond 'jwt'.

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 authenticate by logging in via browser and obtaining an access token. It distinguishes itself from sibling tools like connect or marketplace by focusing specifically on authentication flow.

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 when-to-use guidance: for IDE agents needing authentication, with clear steps for permanent (config) vs session-only (paste) usage. Also mentions alternatives (no args to get link) and how to call with token.

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 beyond annotations by explaining what happens in different scenarios: returns authenticated:true and empty pending[] when all providers are connected, and returns connect_url and per-install URLs when credentials are missing. This adds useful behavioral context beyond the readOnly and idempotent hints.

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, consisting of two sentences that front-load the main purpose and then provide conditional details. No unnecessary information is included.

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 provides a good overview of the tool's behavior and output, covering two primary scenarios. However, it does not exhaustively list all possible states (e.g., partially connected providers), but for a simple status-check tool, it is sufficiently 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, so the schema coverage is 100%. The description does not need to explain parameters, and the baseline of 3 is appropriate since no additional meaning is required.

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 that the tool returns connection status and URLs, and explains the behavior for different states (all providers connected vs missing credentials). This distinguishes it from sibling tools like 'authenticate' which likely handles 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 does not explicitly state when to use this tool versus alternatives. It implies usage for checking connection status, but lacks explicit guidance like 'use this to check if credentials are configured before calling authenticate'.

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 only provide high-level hints (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds critical behavioral details: invoke works even when MCP not installed, requires credentials or payment possibly, returns connect/checkout links, and writes require workspace owner/admin. It also explains the distinction between installed_in_toolkit vs installed_in_workspace. This goes beyond annotations and is very valuable. Missing a bit on idempotency or error cases, but good coverage.

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 long paragraph that is information-dense but not structured (no bullet points or clear action mapping). It is somewhat lengthy and streams many details without clear organization, making it hard to parse. It could be improved by separating the marketplace flow from the prompt library and using bullets for each action. It is not wasteful but could be better structured.

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 enormous complexity (actions, prompt library, install vs invoke, auth), the description covers many critical points like auth requirements, payment, and the difference between one-off and permanent installs. However, it lacks explanations for several actions (resume, subscribe, cancel details) and does not describe return formats for commands. Considering the huge schema (23 params), the description is not fully complete to guide an agent without more 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?

The schema has 0% description coverage, with 23 parameters but the description does not map the parameters to the actions. It mentions 'action=search', 'tool_id', 'arguments', 'mcp_id', and 'prompt_slug' implicitly, but most parameters (e.g., 'request_name', 'prompt_title', 'conversation', 'immediate', 'tier_slug') are left entirely to the schema without clue as to which action uses them. Given the low coverage, the description must compensate but only does minimally.

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 marketplace for MCPs and prompts, with a detailed breakdown of actions (search, describe, invoke, install, etc.). However, the scope is very broad (encompassing both MCP catalog and prompt library), which slightly muddies a single clear purpose. It does distinguish from siblings by positioning itself as the main platform hub versus specific tools like sefaz_ro_nfce_completa_consultar.

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 substantial guidance on when to use each action: 'search discovers MCPs by intent → describe returns one MCP's full profile... invoke RUNS that tool', and explicitly contrasts invoke vs install ('prefer invoke for a single/occasional use; use install only to make an MCP PERMANENT'). It also mentions when to use list_tools and subscribe/cancel. However, it does not explicitly state when NOT to use this tool versus alternatives outside the sibling set, and some actions like resume are not explained, lowering the score.

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 idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description does not contradict these, but it also does not add any transparency beyond the annotations. It does not explain what happens after submission (e.g., if it creates a ticket, sends an email, or logs internally) or any side effects, which is important given that readOnlyHint=false implies a write operation. The description is minimal and does not carry the burden of behavioral disclosure.

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, consisting of two sentences, and front-loaded with the main purpose. It uses efficient language without unnecessary detail. The structure is clear: first the purpose, then a key usage hint. It earns a high score for brevity, but slightly loses because it might have used a bit more space to explain parameters, though that is a completeness issue not a conciseness issue.

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?

This tool has no output schema, no annotations that explain behavior beyond basic hints, and only the description to guide the agent. The description is too brief to be complete for a tool that handles bug reports and feedback. It needs to explain the 'context' parameter, what happens after submission, and possibly mention that the conversation should be a JSON array string. Given the moderate complexity (3 parameters, one required), the description leaves significant gaps in operational understanding.

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 parameter meaning. The description mentions 'message' (the bug report) and 'conversation' (to include recent messages for reproduction), but it does not explain 'context' at all. The parameter 'context' is completely undocumented, leaving the agent with no semantic understanding of what to put there. The description adds some value for 'message' and 'conversation' but fails to cover all 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 clearly states the tool's purpose: to report bugs, missing features, or send feedback. It specifies the resource (issue/feedback) and the action (report/send). It distinguishes from siblings because siblings are about authentication, connectivity, marketplace, a specific consultation, and version info, none of which overlap with bug reporting.

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 the tool: when there is a bug, missing feature, or feedback. It gives a guideline to include the conversation array for reproduction. However, it does not explicitly state when not to use it or mention alternative tools (e.g., for general support or feature requests versus code issues), missing an opportunity for clearer differentiation.

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 context about payment (prepaid credits), data source (official, same as available to citizens), and LGPD compliance responsibilities, which goes beyond annotations. 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 a single paragraph with several sentences, but it is relatively concise and front-loaded with the core purpose. It includes necessary context about payment and legal compliance, though some sentences could be trimmed without losing essential 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 tool has only one parameter and no output schema, the description covers the main purpose and some operational details (payment, data source, LGPD). However, it lacks information about the expected input format and what the response contains, which is important for a tool that returns data. The description is adequate but not 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?

Schema description coverage is 0%, and the description does not explain the 'nfce' parameter beyond its name. The description mentions 'consulta' but does not specify what format the nfce string should take (e.g., access key, number), leaving the agent without guidance on how to construct the 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 queries official SEFAZ RO NFC-e data, specifying the resource (NFC-e Completa) and the source (official). It distinguishes from siblings by focusing on a specific Brazilian tax document query, though it doesn't explicitly contrast with other 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 for querying official Brazilian tax information, but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. It mentions payment via prepaid credits, which is a usage condition, but lacks clear context for selection.

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, covering safety. The description adds that it reports platform and adapter versions, which is consistent with these hints. It adds no extra behavioral details (e.g., no network or side effects), but the tool is trivial and annotations carry the burden.

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?

A single, complete sentence that directly states the action and output. No fluff or redundancy. Perfectly concise.

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 extremely simple with no parameters and no output schema. The description fully covers what the tool does. No additional context is needed for an agent to select and invoke it correctly.

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 there is nothing to explain. Per guidelines, baseline is 4 for 0-parameter tools. The description correctly omits any param detail.

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 shows the current MCP platform and adapter versions. It uses a specific verb ('Show') and resource ('version'), and is unambiguous given the sibling tools (e.g., connect, report_bug) are unrelated.

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-explanatory; it is for retrieving version information. There are no alternatives or complex decision points, so explicit 'when to use' guidance is unnecessary. However, it doesn't mention any context like 'run when diagnosing compatibility,' but the simplicity makes this 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds value by specifying what the state includes (installed MCPs, connection status, accounts, catalog tool counts), which goes beyond the annotations. It doesn't mention any side effects, but given the read-only and idempotent hints, that's not necessary. 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 a single sentence that is concise and front-loaded with the main purpose ('Returns the current toolkit state'). It lists the key elements without unnecessary detail. Every word earns its place.

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 has no parameters, no output schema, and simple annotations, the description is sufficient. It tells the agent what the tool does and what information it provides. It could potentially mention that the output is a summary or list, but the description already covers the key aspects. The tool is simple, so completeness is high.

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 is empty. The description doesn't need to explain parameters, and the baseline for 0 params is 4. The description adds context about what the tool returns, which is useful for the agent to know what to expect.

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 the current toolkit state, listing specific elements: installed MCPs, connection status, connected accounts, and catalog tool counts. This is a specific verb+resource combination that distinguishes it from siblings like show_version (which likely returns version info) and connect/authenticate (which modify state).

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 this is a read-only informational tool for checking toolkit state, which is clear from the context. It doesn't explicitly state when to use it versus alternatives, but the sibling names (connect, authenticate, marketplace) suggest these are action-oriented, while this is a status query. A slight gap is not naming alternatives explicitly, but the purpose is clear enough.

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