SEFAZ PB: NFC-e

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

The description discloses key behaviors beyond annotations: permanent vs session-only login, token format (JWT), and the config header mechanism. It explains that no args returns the link, while token arg sets a session. This adds meaningful context beyond the idempotentHint and destructiveHint 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 moderately sized, front-loaded with the core auth flow, and logically organized with 'Best' and 'Or' for the two modes. Each sentence adds distinct value, though the opening phrase 'log in in the browser, copy the access token' 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?

For a tool with one optional parameter and no output schema, the description covers the auth flow, both authentication modes, token usage, and configuration steps. It does not explain response formatting or error cases, but these are secondary for this auth-focused 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?

With 0% schema description coverage, the description carries the full burden for explaining the token parameter. It specifies the token is a JWT to be pasted and differentiates between passing token vs no args. This gives operational meaning beyond the bare schema field.

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: authenticating IDE agents via browser login and token exchange. It provides two specific modes (permanent config header vs session-only token) and distinguishes itself from sibling tools by focusing solely on 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 explicit usage guidance: 'Best: add it to this server's config as a header...' vs 'Or paste it here for a session-only login', along with calling patterns for token and no-args. It lacks explicit mention of when not to use the tool, but the context is clear enough for agent 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. The description adds value by disclosing the exact return behavior in both the fully-connected and missing-credentials cases, including 'authenticated:true', 'empty pending[]', and 'connect_url'. No contradiction with annotations 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 three short, well-structured sentences: a general purpose statement followed by two conditional branches. Every sentence contributes information, and the most important detail—'connection status and URLs'—is front-loaded.

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 parameterless, read-only tool with strong annotations, the description covers the primary expected behaviors and return contexts. It does not explicitly describe a partially-connected or in-progress authentication state, but the common scenarios of 'all connected' and 'credentials missing' are sufficient 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 input schema is empty and parameter count is 0, so the description is not required to explain parameter details. It still adds useful context by explaining what the no-parameter call will do and under which connection states the return content differs.

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 operation ('Returns connection status and URLs') and distinguishes it from the sibling 'authenticate' tool by emphasizing that it is a read-only status/URL inspection rather than an authentication action. It also specifies concrete expected outcomes, which strengthens the purpose definition.

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 describing branches: when all providers are connected, and when credentials are missing. However, it does not explicitly state when NOT to use this tool or mention that 'authenticate' should be used instead when credentials are missing, leaving the guidance to be inferred from sibling tool names.

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=false, openWorldHint=true, destructiveHint=false, idempotentHint=false) already signal this is a mutating, non-idempotent tool. The description adds meaningful behavioral context beyond those hints: writes require workspace owner/admin, invoke performs a hidden one-off install without bloating the toolkit, and auth/checkout gateways produce retry flows. Not quite a 5 because exact error/edge behavior isn't disclosed, but it substantially enriches the annotation baseline.

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 run-on paragraph mixing two domains (marketplace MCP handling and the prompt library) without any structural separation. While information-dense, it is hard to scan and the em-dash-heavy prose is taxing to parse. Front-loaded content helps, but the lack of paragraph breaks or bullet structure hurts readability for a tool with this much scope.

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 parameters, no output schema, 14 action variants spanning marketplace and prompt library — the description is remarkably complete. It covers the core flow, permission model, install-vs-invoke distinction, retry semantics after connect/checkout, and the prompt library operations. Minor gaps (individual parameter semantics, expected return structures) exist, but for such a broad multi-purpose tool, comprehension 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?

Schema description coverage is 0%, so the description must compensate, and it does meaningfully. It explains the pivotal `action` enum values (search/describe/install/invoke/list_tools/subscribe/cancel/report_bug/request_mcp and the three prompt actions) and their purposes, plus how mcp_id/tool_id/arguments fit the flow. With 23 parameters it can't document every one, but the high-leverage control parameters are contextualized. A 5 would require covering more of the 23 params (e.g., limit, conversation, prompt_vars), so 4 is appropriate.

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 specifies the exact purpose: it is the mcp.ai marketplace catalog and execution engine, covering capability requests and the prompt library. It clearly states the core flow (search → describe → invoke) with specific verbs and resources, and no sibling tool (authenticate, connect, sefaz_pb_nfce_consultar, etc.) overlaps with this capability. This exceeds mere purpose clarity and firmly distinguishes the 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?

Explicit when-to-use guidance is provided: 'prefer invoke for a single/occasional use' vs 'use install only to make an MCP PERMANENT'; subscribe/cancel for billing, report_bug for feedback, request_mcp when nothing fits. The description also calls out exclusions (invoke works even when MCP not installed, returned connect/checkout links require user action then retry). This is textbook usage guidance with named 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 provide idempotentHint and indicate non-read-only/non-destructive behavior. The description adds the instruction to include conversation but does not explain side effects (e.g., ticket creation, notification). Given the annotations, this is adequate but not enriching.

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 concise sentences that clearly convey the purpose and a specific actionable instruction. No unnecessary 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?

The description fails to cover all parameters and does not mention any expected outcome or error handling. While no output schema exists, the tool still lacks important context for a complete 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?

The description only explains the purpose of the 'conversation' parameter ('for reproduction'). It does not clarify 'context' or 'message.' Since schema descriptions are absent, this leaves user confusion about required inputs.

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?

Clearly states the action ('Report') and the object ('bug, missing feature, or send feedback'). Distinguishes itself from siblings like authenticate or show_version by describing a distinct purpose.

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?

Implies usage when an issue is encountered or feedback is needed, and instructs to include the conversation array for reproduction. Does not explicitly mention when to avoid using it, but the context is clear enough.

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 meaningful context: no platform credentials are needed, costs are incurred per query, and the client is responsible for LGPD compliance. This goes beyond the structured annotations and helps the agent understand the operational and legal context.

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 four sentences and front-loads the core purpose. Some legal boilerplate about LGPD and data control is included, which adds length but is arguably necessary for compliance. It remains reasonably concise and readable.

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 has a single parameter and no output schema, so the description carries the burden of explaining behavior. It covers purpose, cost, and data responsibility, but it does not describe the return value, error handling, or the expected format of the 'nfce' parameter. For a simple query tool, this is a noticeable 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?

The input schema has one required parameter 'nfce' with no description, and schema description coverage is 0%. The tool description does not explain what the 'nfce' parameter should contain (e.g., the NFC-e access key format). Since the description fails to compensate for the missing schema details, parameter semantics are unclear.

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 consulta (query) of NFC-e from SEFAZ PB using an official source. The verb 'consulta' and resource 'NFC-e' are specific, and it is clearly distinct from sibling tools like authenticate or marketplace.

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 usage context: it is hosted by the platform, requires no platform credentials, and is paid per query with prepaid credit. It also clarifies that the data is the same available to citizens and not confidential, implying when it is appropriate to use. However, it does not explicitly name alternative tools or state when not to use 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, covering the safety profile. The description adds specificity about what versions are shown (platform and adapter), but does not disclose any additional behavioral traits such as output format or potential errors. Since annotations carry the safety burden, 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 a single, front-loaded sentence with no extraneous words. It clearly conveys the tool's purpose without redundancy, earning the highest score for conciseness and structure.

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 no parameters, no output schema, and comprehensive annotations, the description is complete. It fully explains what the tool does (shows versions) and does not require additional context about return values or usage nuances. The simplicity of the tool makes this description 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?

There are no parameters in the input schema, so parameter-specific guidance is unnecessary. The schema coverage is trivially 100%. The description does not need to add parameter semantics, and the baseline for zero-parameter tools is 4, which is appropriate 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 function: showing the current MCP platform and adapter versions. This is a specific verb ('Show') with a clear resource (versions), and it 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?

The description implies when to use it: whenever a user needs to know the versions of the MCP platform or adapters. It does not explicitly mention alternatives or exclusions, but given the simplicity and unique purpose among siblings, it is clear enough without explicit 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about the returned information (installed MCPs, states, accounts, tool counts) without contradicting any 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, well-structured sentence that front-loads the core purpose ('Returns the current toolkit state') and then lists the key output categories. Every part of the sentence adds value, 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?

For a no-parameter, read-only introspection tool, the description fully covers what is returned and is complete enough for an agent to select and invoke it correctly. The absence of an output schema is mitigated by the clear enumeration of the returned state information.

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 schema coverage is complete and there is nothing to clarify. The description compensates by explaining what the toolkit state contains, which is the most relevant semantic information for an agent invoking this 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 uses a specific verb ('Returns') and names a clear resource ('current toolkit state'), then enumerates the exact contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This makes it easy to distinguish from sibling tools like show_version and 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 clearly implies this is the tool to call when an agent needs a state overview of the toolkit, but it does not explicitly state when to use it versus alternatives or when not to use it. Given the context of action-oriented siblings, the usage intent is reasonably clear but not fully explicit.

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