SEFAZ PE: NFC-e

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

Adds behavioral details beyond annotations: describes the need for a browser login step, distinguishes between permanent and session-only auth, and explicitly states behavior with and without the token parameter. No contradiction with the idempotentHint=true annotation since the auth process can be safely re-invoked.

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 somewhat wordy, but every sentence contributes to the reader's overall understanding of the auth flow. The two-path explanation is front-loaded and logically ordered from permanent to session-based, making it both concise and 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?

For a single-parameter tool with no required params and no output schema, the description is highly complete: it covers the browser login, token handling, permanent vs session options, and no-args behavior. Minor gaps include missing error handling or response shape, but overall satisfies all needed 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 0% schema coverage, the description fully compensates by explaining the optional 'token' parameter as a JWT to paste for session-only login and clarifies that calling with no arguments returns a link. It does not describe the output format, but the single token is well contextualized.

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 an authentication/log-in flow for IDE agents, using a browser token or pasted JWT. It distinguishes itself from the general 'connect' sibling through its focus on obtaining and using an access token, though it does not explicitly contrast with alternatives.

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 specific usage guidance: permanent bearer header via config for a non-expiring connection, or session-only login by passing a JWT token, or no args to receive a link. It gives clear scenarios, including 'after the user pastes' and 'with no args to get the link', but does not explicitly state when not to use this 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 the operation read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail by specifying the two observable states: connected providers return authenticated:true and empty pending[], while missing credentials produce connect_url and per-install URLs. It could further clarify partial-connection states, but this is solid 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?

Two dense sentences, first sentence states the core purpose, second explains the conditional outputs. Every phrase contributes without repetition or unnecessary context.

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, the description is nearly complete. It documents expected return signals for both the fully-connected and missing-credentials cases. However, there is no explicit coverage of partial connection states, and since no output schema exists, the description carries the entire burden of explaining outputs.

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 parameter semantics are not applicable. Baseline 4 applies because there is no schema detail to explain and no hidden or optional parameters 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 clearly states the tool's purpose: it 'Returns connection status and URLs.' It distinguishes itself from sibling tools by specifying authenticated/pending and URL outputs, so there's no ambiguity about what this tool does.

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 use when an agent needs to check whether providers are connected or obtain connection URLs. However, it does not explicitly state when not to use it or compare it with alternatives such as 'authenticate' or 'show_version.'

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?

It discloses high-value behavior absent from the annotations: invoke works even if the MCP is not installed, returns connect/checkout links for missing auth or payment, writes require owner/admin permissions, and searchers/describes flag installed vs workspace status. This goes well beyond the raw annotation flags.

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 front-loaded, leading with the marketplace's primary purpose and the main search/describe/invoke flow. It is a long single paragraph, slightly harder to scan, but each sentence adds real value and very little text is waste.

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 large input schema, lack of output schema, and empty per-deciones param descriptions, the text answer covers the essential flow well: discovery, description, one-off execution, permanent installation, billing/auth edge cases, and the prompt-library feature. Some parameters' exact syntax/behavior and output shapes are still left implicit, but the overall operation model is unusually 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 description adds meaning for key params including the semantic groups action, mcp_id, tool_id, arguments, prompt_vars, and prompt_* fields. However, with 23 parameters and 0% schema-description coverage, many params like immediate, conversation, request_name, tier_slug, cancel_reason, and prompt_targets still lack direct explanation. The prose compensates partially, not fully.

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 establishes the marketplace as the in-platform catalog and launcher for MCPs/tools, covering discovery, execution, installation, billing, and prompt-library operations. It gives a concrete core flow—search→describe→invoke—and distinguishes it from simple query or install 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 gives explicit guidance on when to use each operation: prefer invoke for occasional use, use install to make permanent, use list_tools to see callable tools, request_mcp when nothing fits, subscribe/cancel for billing. This is strong when-to-use and when-not-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 already mark the tool as idempotent, non-destructive, and not read-only. The description adds value by instructing to include the conversation array for reproduction, which is beyond what annotations provide. No contradictions 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 two sentences, immediately states the purpose, and provides the key instruction about the conversation array. No fluff or redundant phrasing.

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 only three parameters and no output schema, the description adequately covers the main action and one critical parameter. It could be more complete by explaining the 'context' parameter or any follow-up behavior, but given the simplicity, it is largely 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. It explicitly explains the conversation parameter ('Include the conversation array with recent messages'), which clarifies its purpose. However, 'context' and 'message' are not described; 'message' is implied as the report content, but 'context' remains undefined. This partial compensation yields a middle score.

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: report a bug, missing feature, or feedback. It uses a specific verb ('report') and resource ('bug/feature/feedback'), and is distinct 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?

It provides clear context on when to use this tool (to report issues or give feedback) and mentions including the conversation array for reproduction. However, it does not explicitly state when not to use it or name alternative tools, but given the unrelated siblings, the usage context is fairly 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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it is a paid per-query operation, hosted by the platform, requires no platform credentials, and returns only non-secret official data subject to LGPD controller responsibilities. No contradiction exists.

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 main purpose: 'SEFAZ PE: NFC-e, consulta em fonte oficial.' The additional payment/no-credential and LGPD context are relevant operational details, though the legal sentence adds minor length without directly impacting tool invocation.

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 main tool context reasonably well: official source, payment model, credentials, and data sensitivity. However, the absence of any explanation of the 'nfce' parameter format and the lack of an output schema description leave notable gaps for an agent selecting and invoking the tool 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 schema has a single string parameter 'nfce' with no description, and the schema description coverage is 0%. The description mentions NFC-e generally but never specifies what value should be passed—whether it is the full access key, date/full receipt code, or some other identifier—so an agent would have to infer the input format from the parameter name alone.

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 NFC-e data from SEFAZ PE via an official source, using a specific verb ('consulta') and a clear resource/scope. It distinguishes itself from the unrelated sibling tools by focusing on a SEFAZ-specific lookup.

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 practical context: no platform credentials are required, usage is billed from prepaid credit, and the data is the same public information available to citizens. It does not explicitly discuss when not to use the tool or name alternatives, but the context is clear enough for this narrow lookup 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds minimal behavioral context beyond stating the scope (MCP platform and adapter versions). It does not contradict annotations, but it also does not disclose any additional behavioral aspects like output format or prerequisites.

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 with no filler. Every word adds meaning, making it highly concise and well-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 tool's simplicity (no parameters, no side effects, read-only) and the presence of informative annotations, the description is complete. It accurately conveys the core function without needing to explain return values or complex behavior. The output schema is absent, but for a version-showing tool, this is 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?

The tool has zero parameters, and the schema coverage is 100% (vacuously). The description does not need to elaborate on parameters since there are none. Baseline for 0 params is 4, and the description properly omits 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 function: 'Show the current MCP platform and adapter versions.' This uses a specific verb ('show') and identifies the resource (MCP platform and adapter versions). It distinguishes from siblings like authenticate, connect, and marketplace, 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 does not mention explicit alternatives or when-not-to-use, but the tool is simple and self-explanatory. Given its singular purpose, the usage context is implied clearly; there is no ambiguity about when to invoke it.

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 enhances transparency by specifying exactly what aspects of the state are returned (installed MCPs, connection status, accounts, catalog tool counts), providing more behavioral detail than annotations alone. No contradictions found.

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, grammatically efficient sentence that front-loads the main purpose ('Returns the current toolkit state') and lists the key details without any fluff. No unnecessary words or redundant 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?

The tool is simple (no params, no output schema, no nested objects) and fully describes its output in the description. The annotations cover safety characteristics, and the description covers the content of the state returned. Nothing is missing for the agent to use this tool 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, and the schema is empty with 100% coverage (trivially, as there is nothing to cover). Per the scoring baseline for tools with no parameters, a score of 4 is appropriate. The description does not need to explain parameters since none 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 explicitly states the verb 'Returns' and identifies the resource as 'current toolkit state' with a detailed list of contents (installed MCPs, connection status, accounts, catalog tool counts). This clearly distinguishes it from sibling tools like connect or authenticate, which perform actions rather than report 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 makes it clear that this tool provides state information, which implicitly signals when to use it (e.g., to check connections or accounts). However, it does not explicitly mention alternatives or situations where this tool should not be used, though that is less critical for a simple inspection tool.

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