SEFAZ BA: NFC-e

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

Adds meaningful context beyond annotations by explaining the permanent vs. session nature of authentication and the token format (JWT). While annotations already note idempotency and non-destructiveness, the description provides valuable behavior around persistence and link generation. 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 front-loaded with purpose and concise enough, but includes some verbose explanation of the config option. It is well-structured and every sentence adds value, with minor room for tightening.

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 both usage modes and token semantics thoroughly. Lacks explicit description of return values or errors, but given the simple 1-param schema, absence of output schema, and clear annotations, the description is sufficiently complete for an agent to use 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 schema has 0% description coverage, so the description must fully compensate. It explicitly explains the 'token' parameter as a JWT, optional (no args returns a link), and its role in session login. This adds complete significance beyond the bare schema definition.

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 via browser login and token exchange. It uses specific verbs ('log in', 'copy token') and resource ('access token'), and distinguishes itself from siblings like 'connect' and 'marketplace' by focusing 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 guidance on two usage modes: permanent connection via config header, and session-only via passing a token or no args to get a link. It tells the user exactly when to use each approach, effectively serving as a usage guide.

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 idempotentHint=true. The description adds behavioral details beyond annotations: it describes the return values (authenticated:true, pending[], connect_url, per-install URLs) and the conditions under which each appears. This enriches the agent's understanding without contradicting 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 concise: two sentences, both front-loaded with the core purpose and key behavior. Every clause adds value, with no fluff or redundancy. It is appropriately sized for a parameterless status-check tool.

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?

With no output schema and no parameters, the description carries the full burden of explaining return behavior. It covers the main states (all connected vs missing credentials) and the relevant return fields. For a simple status tool, this is complete and 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, so per the rubric the baseline is 4. The description correctly omits any parameter details, as none exist. It does not add parameter-related information, but none is needed.

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: 'Returns connection status and URLs.' It specifies the two possible outcomes (all providers connected vs missing credentials) and explains the return values. This distinguishes it from siblings like authenticate, which performs a different action.

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 explaining what the tool reports in different states, but it does not explicitly say 'use this to check connection status' or mention alternatives. However, given the tool's simplicity and context, the implied usage 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?

The description adds important behavioral details beyond the annotations: invoke actually runs uninstalled MCPs one-off, credential and payment failure produce connect/checkout links, writes require workspace owner/admin, and search/describe flags installed status. It clearly explains side effects and authorization requirements, and does not contradict 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 a dense, single paragraph with highly useful content but poor visual structure; key concepts like the search→describe→invoke flow, install-vs-invoke, billing, and the prompt library are jammed together with semicolons and asides. Every sentence adds value, but the format makes it harder to parse quickly.

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?

Despite being very informative on the primary workflows, the description is not fully complete for a tool with this many actions and parameters. The resume action and several parameters such as immediate, limit, prompt_targets, and cancel_reason are never explicitly explained, and no output/return structure is described for any action beyond the payment and connect links.

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 23 parameters have zero schema descriptions, so the description must compensate. It does explain the core parameters and flow (action, query, mcp_id, tool_id, arguments, and prompt_vars via get_prompt). Much of the surface area remains undocumented, however, including resume, immediate, tier_slug, cancel_reason, and the request_mcp fields, leaving some parameters ambiguous.

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 is the official mcp.ai marketplace for discovering, describing, and running MCPs/tools, plus managing the prompt library. It includes concrete action flows (search → describe → invoke), capability request examples, and explicit coverage of prompt management, which distinguishes it clearly from sibling tools like show_version 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 gives explicit usage guidance: use search to discover, describe to inspect, invoke to run even without installing, and install only for permanent additions. It also names list_tools, subscribe/cancel, report_bug, request_mcp, and the prompt-library functions as alternatives, so the agent knows when to use each behavior.

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 safety profile: non-read-only, non-destructive, and idempotent. The description adds useful context by explaining that the conversation array aids reproduction, but it still does not disclose what side effects occur after reporting or whether authentication is required.

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 concise sentences with no filler. The primary purpose is front-loaded, and the reproduction guidance is placed at the end without unnecessary 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 simple three-parameter tool with no output schema, the description covers the core action, the required message, and the optional conversation data. It is sufficiently complete to invoke the tool, though it could explain the context parameter and post-submission behavior.

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 explains the conversation parameter as an array of recent messages for reproduction, but it does not clarify the meaning of the context parameter. The required message parameter is self-explanatory from the tool's purpose.

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 reports bugs, missing features, or feedback, using a specific verb and resource. It is distinct from sibling tools such as authenticate, marketplace, and show_version, making its purpose unambiguous.

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 usage context: use it to report a bug, missing feature, or send feedback. It also instructs agents to include the conversation array for reproduction, but it does not explicitly mention when not to use it or name 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?

Beyond the annotations (read-only, idempotent), the description adds transparency about data sourcing (official Brazilian sources), non-confidential nature, and legal compliance (LGPD). This provides a clear picture of what the tool does and its side effects (or lack thereof).

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, covering essential aspects in a few sentences. It is slightly repetitive (e.g., mentions 'oficial' multiple times) but overall well-structured and not overly verbose.

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 sufficient context for a simple query tool: purpose, data source, payment model, and legal considerations. It does not specify output format or error handling, but given the tool's straightforward nature, the provided details are adequate.

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 only parameter 'nfce' is named descriptively but the description does not elaborate on its format or meaning (e.g., access key, QR code). The description adds no additional clarification beyond the parameter name, so the semantic coverage is minimal.

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 BA (official source), specifying it is a consultation. It distinguishes itself from the sibling tools by focusing on NFC-e, which is unique among the listed 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 mentions practical usage details such as being hosted by the platform, no credentials needed, pay-per-query with prepaid credits, and that it queries non-confidential official data. It does not explicitly compare to alternatives, but the purpose is distinct enough to infer when 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 and idempotentHint=true, so the safety profile is covered. The description adds specificity about what versions are shown (MCP platform and adapter) but does not elaborate on output format or side effects. It does not contradict annotations and provides sufficient context for a read-only query.

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 with no filler. It communicates the essential information in a front-loaded manner, earning full marks for efficiency.

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 trivial complexity (no parameters, no output schema, clear annotations), the description is complete. It fully defines what the tool does without requiring additional details. The annotations cover behavioral traits, so the description suffices.

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 zero parameters, so the schema already covers everything. The description appropriately omits parameter details. Baseline for 0 params is 4, and the description does not need to compensate for anything.

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 verb ('Show') and the resource ('current MCP platform and adapter versions'), making its purpose unambiguous. It distinguishes itself from sibling tools like authenticate or connect, none of which relate to versioning.

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 that this tool is for retrieving version information, but does not explicitly mention when to use it versus alternatives. Since no sibling tool serves a similar purpose, the absence of exclusions is acceptable, and the intent is obvious.

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 clear. The description adds value by specifying what state is returned (installed MCPs, connection status, accounts, catalog tool counts), but it does not disclose details like whether the state is cached, how fresh the data is, or any rate limits. With annotations covering the safety profile, a 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 sentence that is concise and front-loaded with the key purpose ('Returns the current toolkit state'). It lists the specific elements returned without any fluff or redundancy. 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 strong annotations (readOnlyHint, idempotentHint, destructiveHint), the description is complete enough for an agent to understand what the tool does and what it returns. It could potentially mention whether the state is real-time or cached, but for a simple informational 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 description coverage is 100% (vacuously, since there are no properties). The description adds meaning by explaining what the tool returns, which is the only relevant semantic content. With no parameters, a baseline of 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 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 sibling tools like authenticate, connect, and show_version.

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, but it does not explicitly state when to use it versus alternatives. Sibling tools like show_version and marketplace could overlap in purpose, but no exclusions or alternative guidance is provided.

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