SEFAZ SP: NFE

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

Annotations indicate non-read-only, idempotent, and non-destructive behavior The description builds on this by explaining the login workflow, token copying, and session-permanent distinction. It does not detail edge cases (e.g., expired tokens or errors), but the core behavior is transparent for an auth tool.

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?

Three compact sentences cover the core workflow, the recommended permanent setup, and the session-only alternative, all front-loaded with the most important actions. Code formatting for token usage improves readability. No unnecessary filler.

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 auth tool with one optional param and no output schema, the description provides enough context: how to initiate login, what to do with a token, and how to choose session vs permanent. It could mention return values or error/expiry behavior, but these are not essential for selecting and invoking.

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 lists one optional string parameter with no schema-level description (0% coverage). The description compensates well by showing the exact object syntax `{ token: "<jwt>" }` and clarifying that omitting the parameter retrieves the link for browser login. This fully conveys the parameter's meaning and optionality.

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 resource (MCP.AI for IDE agents) and the action (log in, copy access token, provide token). It distinguishes itself from sibling tools like connect by focusing specifically on authentication/access-token handling.

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 presents two usage paths: permanent configuration via header versus session-only token paste, and explains when to call with a token versus with no arguments. This gives clear guidance on the exact call variations and their contexts.

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 so safety is covered. The description adds valuable behavioral detail about conditional returns: when connected vs missing credentials, including the URLs. This goes beyond annotation data.

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 sentences convey all necessary information with zero ambiguity or wasted words. Each clause adds value.

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 fully explains the return values in both states (connected and missing credentials), covering what an agent needs to know. No output schema exists but the description compensates fully 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?

No parameters exist, so the baseline is 4 per rubric. The description does not need to explain parameters, and schema coverage is vacuously 100%.

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 it returns connection status and URLs, with specific behavior under different conditions. This distinguishes it from siblings like 'authenticate' (which likely performs authentication) and 'toolkit_info' (general 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 implies it is used to check connection state, but does not explicitly say when to use it vs alternatives. It provides clear context on what it returns but no exclusions or comparisons to sibling tools.

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 substantial behavioral context beyond the annotations: invoke works even when the MCP is not installed, returns connect/checkout links for auth/payment failures, one-off runs do not bloat the toolkit, writes require workspace owner/admin, and prompt links open without login. This goes well beyond the generic 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 packed with useful content but delivered as one dense, unbroken paragraph. It is front-loaded with the core flow and the crucial 'invoke works without install' detail, but scanning it is difficult. A structured or bulleted format would improve readability without losing 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?

For a complex dispatch tool with no output schema and minimal annotation detail, the description covers the main workflows, permissions, auth/payment edge cases, and the prompt library remarkably well. However, it omits some actions/parameters such as resume, cancel_reason, immediate, and the detailed inputs for prompt publishing, leaving gaps for an agent to infer.

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 23 parameters and 0% schema description coverage, the description carries a heavy burden, but it only explains the action values and a few high-level concepts. Many parameters such as limit, immediate, tier_slug, conversation, prompt_vars, request_details, and report_context are never mapped or explained. The action enum semantics help, but coverage is insufficient for a tool this large.

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 frames the tool as the official mcp.ai marketplace catalog and execution layer: 'the in-platform catalog of every MCP/tool, AND the way to run them.' It names the concrete workflow (search → describe → invoke) and distinguishes this tool from siblings by explaining its central role and sub-actions.

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?

Usage guidance is explicit and actionable: 'use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use.' It also tells when to use list_tools, report_bug, request_mcp, and the prompt-library functions, giving clear alternatives within the 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 indicate idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds that this is a reporting/sending action, but it does not disclose side effects such as where the report goes, whether a confirmation is returned, or any rate limits. The instruction to include the conversation array provides some behavioral context, but not deep transparency. 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 two sentences long, front-loaded with the core purpose, and both sentences earn their place. The second sentence adds a critical usage detail without redundancy. It is efficient 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?

For a simple tool with 3 parameters and no output schema, the description covers the primary purpose and one parameter, but leaves 'context' unexplained and does not describe the expected outcome or side effects. It is adequate for basic understanding but not fully complete for an agent deciding whether to invoke it in all cases.

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 for reproduction'), which adds meaning. However, it does not clarify the 'context' parameter and only implicitly covers 'message' as the content of the report. Partial compensation for the missing schema descriptions, but gaps remain.

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 with a specific verb and resource: 'Report a bug, missing feature, or send feedback.' It distinguishes itself from sibling tools like authenticate, connect, and marketplace, none of which cover feedback or bug reporting. The phrase is unambiguous and actionable.

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: for reporting bugs, missing features, or feedback. It also provides a concrete usage instruction: 'Include the conversation array with recent messages for reproduction.' However, it does not explicitly mention exclusions or alternative tools, though the sibling list makes alternatives irrelevant. Overall, the context is clear but lacks formal 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 it read-only, and the description adds valuable context: hosted by the platform, no credentials required, public (non-confidential) data, and LGPD compliance responsibilities ('O cliente é o controlador dos dados'). This goes beyond the annotations to clarify data handling and legal implications.

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 run-on sentence that packs multiple facts (source, hosting, credentials, payment, data type, legal responsibility) without clear structure. It's not excessively long but could be better organized into clear points for readability.

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 read-only query tool, the description covers key aspects like data sensitivity and controller responsibility, but omits what the response will contain (e.g., refund status, invoice details) and potential error cases (e.g., invalid key, rate limits). It is minimally viable but leaves gaps for an agent needing to handle edge cases.

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 'nfe' is completely undocumented in the schema (0% coverage) and the description does not clarify what format or value it expects (e.g., a 44-digit key, or invoice number). Since there is no description compensation, the agent is left guessing the exact input format.

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 a query for NFE (Nota Fiscal Eletrônica) from SEFAZ SP, specifying the official source and the read-only nature ('consulta em fonte oficial'). It distinguishes itself enough from generic sibling tools, though it could be more explicit that 'nfe' is the invoice access key.

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 implicitly communicates usage context: no platform credentials needed ('sem credenciais da plataforma') and pay-per-query with prepaid credit ('pague por consulta com crédito pré-pago'). However, it does not explicitly state when to use this vs. alternatives or provide exclusions, leaving room for interpretation.

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, establishing a safe read operation. The description adds context by specifying that both 'MCP platform' and 'adapter' versions are included, which clarifies the tool's output scope beyond the generic 'version' name.

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, focused sentence with no wasted words. It is front-loaded with the action and resource, making it immediately scannable.

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 no-parameter version tool with strong annotations, the description is adequate. It states the tool's purpose and scope, though it does not specify the output format or whether it returns structured data. This is a minor gap given the low complexity.

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 trivially 100%. With no parameters to document, the description does not need to add semantic detail; the baseline of 4 applies.

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 ('Show') and names the exact resources ('current MCP platform and adapter versions'), making the tool's function unmistakable. It differentiates from siblings like toolkit_info and report_bug by focusing solely on version information.

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?

No guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites. The intended use case is only implied by the name and description, not explicitly stated.

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 detailing what the returned state contains, such as connection status and account bindings, which helps the agent interpret the output. 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 a single sentence that is front-loaded with the core action ('Returns the current toolkit state') and then provides a concise enumeration of the included information. Every word serves a purpose with no 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 zero-parameter information tool without an output schema, the description sufficiently communicates what the agent will receive. It lists the main categories of returned data, giving the agent enough context to invoke the tool and interpret the result.

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 effectively 100%. Per rubric, a baseline of 4 is appropriate; the description does not need to compensate for any undocumented 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 specifies the tool's function: returning the current toolkit state. It identifies specific elements (installed MCPs, connection status, accounts, and catalog tool counts) that distinguish it from sibling tools. The verb 'returns' reinforces its read-only nature.

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 the toolkit state is needed) but does not explicitly mention alternatives or when not to use it. Compared to calibration examples like get_calls, which names an alternative, this lacks explicit usage exclusions, though the purpose is self-evident.

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