SEFAZ BA: NFC-e (Completa)

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

Goes beyond annotations by explaining the two modes (permanent via config vs. session-only via pasted token) and the 'no args returns a link' behavior. It does not detail failure states or response shapes, but the key behavioral aspects are disclosed.

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 compact but information-dense, front-loaded with the tool's purpose and structured with 'Best:' and 'Or' to clearly separate the two usage paths. Every sentence adds actionable value without fluff.

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 an authentication tool with minimal schema and no output schema, the description covers the main flow (get link, paste token), the session vs. permanent distinction, and the target audience (IDE agents). It lacks explicit return details for the token-submission path but is otherwise 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?

Schema coverage is 0%, and the description fully compensates by explaining the single `token` parameter (a JWT pasted by the user) and the optional no-args form. This is all an agent needs to invoke the tool correctly.

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 to MCP.AI via a browser login, either by pasting a token for session-only access or by retrieving a login link. The verb 'log in' and the specific resource (MCP.AI) make it unambiguous and distinct from generic sibling names like '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?

Provides explicit guidance: the recommended permanent approach is adding the token to the server config as a header, while this tool is for session-only login or obtaining the login link. It also specifies exactly when to call with a token (`{ token: "<jwt>" }`) versus with no args.

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=true and idempotentHint=true, so the description goes beyond by detailing what is returned in each scenario (authenticated:true, empty pending[], connect_url, per-install URLs). This adds valuable behavioral context not present in 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 extremely concise, using only two sentences to convey the purpose and two key behavioral states. It is front-loaded with the core functionality 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?

For a simple, parameterless tool with no output schema, the description adequately covers the essential behaviors and return values in both connected and disconnected states. It is complete enough for an agent to understand what to expect without further clarification.

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 baseline is 4. The description correctly addresses the parameter-free nature by focusing on return values, which is sufficient given the empty schema.

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: 'Returns connection status and URLs.' This is a specific verb-plus-resource structure that distinguishes it from siblings like authenticate (for authentication) and show_version (for version info). The description also explains the behavior in different states, further clarifying what it 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 provides clear context on when to use the tool by explaining its behavior under different connection conditions (e.g., 'When all providers are connected... When credentials are missing...'). However, it does not explicitly name alternatives or state when not to use it, so it falls 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?

No annotations describe write permissions, payments, or auth, but the description discloses that writes require workspace owner/admin, invoke returns a connect link when credentials are needed, paid tools return a checkout/top-up link when the wallet is empty, and invoke runs a hidden one-off install. This goes well beyond the sparse readOnly=false/openWorld=true 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 front-loaded with the core purpose and key invoke-vs-install distinction. However, it is one long paragraph covering ~14 actions and 23 parameters with no bullets or headings, and it has some redundancy between 'covers capability requests' and the subsequent 'core flow' explanation.

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, no output schema, and minimal annotations, the description covers a lot: the main flows, auth/payment behavior, permissions, installed-in-toolkit vs workspace flags, and the prompt library. It does not describe concrete output shapes for search/list_tools or edge-case behavior, but it is adequate for an AI agent to select and invoke the 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 coverage across 23 parameters, the description carries a heavy burden. It explains the main action enum values and core flow (search, describe, invoke, install, list_tools, etc.), and mentions prompt variables, but many parameters such as cancel_reason, immediate, tier_slug, prompt_targets, report_context, and request_details are never tied to their actions or formats.

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 opens with 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them', giving a specific resource and scope. It clearly defines the core search → describe → invoke flow and distinguishes its catalog/run role from sibling tools like authenticate, connect, and toolkit_info.

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 explicitly contrasts invoke ('one-off, without adding the MCP to the toolkit') versus install ('PERMANENT in the active toolkit') and says 'prefer invoke for a single/occasional use'. It also gives context for list_tools, subscribe/cancel, report_bug, request_mcp, and the prompt-library actions, providing actionable when-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?

The annotations provide idempotentHint=true and destructiveHint=false, but the description does not elaborate on side effects or outcomes. It does give a behavioral instruction to include the conversation array, which adds some transparency, but it does not discuss what happens after submission (e.g., ticket creation, confirmation).

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 are directly to the point. It avoids unnecessary details and is well-structured for quick comprehension.

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 enough context for basic usage but lacks information about return values or outcomes (since there is no output schema). It also does not mention error handling or asynchronous behavior, making the overall context incomplete for advanced scenarios.

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 explains the 'conversation' parameter by stating it should contain recent messages for reproduction, adding value beyond the schema. However, it does not clarify the 'context' parameter or the exact format of 'message', leaving some parameters underdescribed.

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: reporting bugs, missing features, or feedback. It also specifies the need to include the conversation array, making the purpose distinct from sibling tools like authentication or connection 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 implicitly indicates when to use this tool (when reporting an issue) and provides instructions on including the conversation for reproduction. However, it does not explicitly mention alternatives or edge cases, but given the sibling tools are unrelated, the usage context is 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context: it is hosted by the platform, requires no platform credentials, is paid per query with prepaid credits, and clarifies data privacy (LGPD) and that data is not confidential. This goes beyond annotations and helps the agent understand operational constraints.

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 three sentences, each adding distinct information: purpose, operational details, and legal context. It is concise and front-loaded with the core purpose. No wasted words, though it could be slightly more structured with bullet points, but it is acceptable.

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 (one parameter, no output schema), the description covers the essential aspects: what it does, how it is accessed (paid, prepaid), and legal considerations. It does not describe the return format, but since there is no output schema, the description could have mentioned what the response contains. However, for a simple query tool with good annotations, this is reasonably 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 has one required parameter 'nfce' with no description, and schema description coverage is 0%. The description does not explain what 'nfce' should contain (e.g., the access key format, length, or example). However, with only one parameter and a clear name, the meaning is somewhat inferable, but the description should have provided format details to compensate for the lack of schema documentation.

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 the official SEFAZ BA source for complete NFC-e data, distinguishing it from a generic query by specifying the state (BA) and type (Completa). It does not explicitly contrast with sibling tools, but the siblings are unrelated (auth, connect, etc.), so the purpose is clear enough.

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 tax documents, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. It does clarify that it is a paid per-query service with prepaid credits, which gives some context, but no exclusions or alternative tool references.

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 and destructiveHint=false, so the safe-read nature is covered. The description confirms a read operation but adds no behavioral detail beyond what annotations convey (e.g., no performance, output format, or edge-case info). Does not contradict 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, concise sentence that covers the essential purpose. It could be slightly more specific about output format, but for a simple getter, this is appropriately brief and 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?

The tool is trivial: no parameters, no output schema, and annotations cover safety. The description fully covers what an agent needs to use this tool correctly. The task is simple enough that no additional detail is necessary.

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 0 parameters, so the description's only job is to state what the tool returns, which it does. The description clearly indicates the output will be version information for MCP platform and adapters, which is sufficient for a no-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 'Show the current MCP platform and adapter versions' uses a specific verb ('Show') and identifies the exact resource ('MCP platform and adapter versions'). It's clear and distinct from siblings like authenticate or connect, though it doesn't name a specific sibling as an alternative.

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 its use as a simple status/version query, but provides no explicit when-to-use guidance or mention of alternatives; however, given its generic nature, minimal guidance is needed. It doesn't mislead but offers no explicit context.

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=false, so the safety profile is covered. The description adds value by detailing what the returned state includes, which goes beyond the annotations and helps the agent understand the tool's output 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 entire description is one concise sentence that front-loads the purpose and uses a colon to list the returned components. There is no filler, repetition, or irrelevant detail.

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 information tool, the description is fully sufficient: it explains exactly what state is returned and covers the main aspects an agent needs. With no output schema, the enumerated contents serve as a clear substitute for return-value documentation.

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 100% schema description coverage, so there are no parameter semantics to clarify. Per the rubric, this warrants a baseline of 4 since the description does not need to compensate for missing parameter context.

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 clearly identifies the resource ('current toolkit state'), then enumerates the exact contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This distinguishes it from siblings like show_version or authenticate by focusing on state inspection rather than action or version details.

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 the current toolkit state, giving clear context for when it applies. It does not explicitly name alternatives or exclusions, but the scope is clear enough for an agent to select it over sibling action-oriented tools.

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