SEFAZ SP: NFC-e

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

The description adds meaningful behavior beyond annotations: it explains that a config header yields a permanent, non-expiring connection while passing a token gives session-only access. It also indicates that calling with no arguments returns a link. Annotations already note idempotent and non-destructive, but the description provides useful persistence 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 a single run-on paragraph, starting with a slightly informal 'MCP.AI for IDE agents (Cursor, etc.):' and mixing setup instructions with invocation examples. It contains useful details but would benefit from clearer structure or bullet points; it is not as concise as it could be.

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 output schema and only sparse annotations, the description carries a heavy burden. It covers the main usage paths and token persistence model, but it omits details like what the returned link looks like, how success/failure is communicated, and any security/caveat information. For a simple one-param optional tool it is above average, but still has gaps.

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% (the optional 'token' parameter is just a string with no description), but the description compensates by explaining the token is a JWT and giving usage examples: call with { token: '<jwt>' } or no args to get the link. This fully covers the parameter's meaning and the no-arg behavior.

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 authenticates an IDE agent (like Cursor) with MCP.AI, specifying the browser login and token capture. It is specific enough about the resource and action, but it does not explicitly differentiate from the sibling 'connect' tool, so it misses full clarity.

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 explicit usage modes: no args to get a link, passing a token for session-only login, and a recommended config header approach for a permanent connection. It does not mention when not to use this tool or direct users to alternatives, but the in-tool mode guidance is strong.

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 already declare readOnlyHint and idempotentHint. The description adds valuable context about the output shape and states (authenticated:true, empty pending[], connect_url), which helps the agent understand behavior beyond 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 brief (two sentences) and directly states the function and conditions, with no redundant or irrelevant 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?

Given no parameters and no output schema, the description fully explains the function and its output conditions, making it complete for the agent to use 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?

There are no parameters, so the description adds no parameter-specific meaning. Per the rubric, a baseline of 4 is appropriate for zero 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 states the tool returns connection status and URLs, and explains the output conditions (authenticated:true vs connect_url), making its purpose specific and distinct from sibling tools like authenticate or 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 does not explicitly state when to use this tool versus alternatives, but the context of checking connection status implies its usage. It provides conditional outputs but lacks explicit guidance on when to prefer this over other 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 goes far beyond the sparse annotations by explaining subtle behaviors: invoke works even without installation, auth problems produce a connect link, payment problems produce a checkout link, and writes require workspace owner/admin. It does not contradict annotations, and readOnlyHint false is consistent with the documented write actions.

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 information-dense but structured as one long paragraph with semicolon-separated ideas. It is front-loaded with the core marketplace flow and avoids fluff, yet the amount of content would benefit from action bullets or separate prompt-library section to improve scannability.

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 high complexity, 23 parameters, and no output schema, the description still covers the main behaviors: discovery via search/describe, one-off invocation, local credentials/payment flows, installed-vs-workspace flags, permission requirements, and prompt-library actions. It is not fully complete because per-action return values and exact parameter-to-action mapping are still unresolved, but it is substantially comprehensive.

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?

Despite a 23-parameter schema with 0% property coverage, the description only implicitly covers a few fields like action, query, tool_id, and arguments-related concepts. It does not map most parameters to their actions—for example prompt_targets, cancel_reason, tier_slug, conversation, report_context, request_details, and immediate remain unexplained, leaving the agent guessing.

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 a clear, specific statement: 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It enumerates core actions (search, describe, invoke, install, list_tools) and distinguishes itself from a prompt library, making the tool's dual purpose unmistakable.

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 decision guidance: 'prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT', and 'list_tools lists what is callable right now'. It also points to request_mcp when nothing fits and report_bug for feedback, creating a useful decision tree for the agent.

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 context about including the conversation array for reproduction, which is useful. However, it does not disclose what happens after reporting (e.g., whether it's logged, sent to developers, or if there's an acknowledgment). Annotations indicate idempotentHint=true and destructiveHint=false, but the description does not elaborate on side effects or authentication needs. Since annotations cover safety, a baseline 3 is suitable.

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, front-loaded with the main purpose and then the key instruction about conversation. Every sentence contributes value, with no redundancy. It is appropriately sized for a simple reporting 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?

Given the tool's simplicity (3 params, no output schema, no nested objects), the description is mostly sufficient. It covers the primary use case and the reproduction instruction. But it lacks details on parameter formats (e.g., what 'message' should contain) and expected outcomes. With annotations covering idempotency and non-destructiveness, a 3 is reasonable.

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, but it only mentions the 'conversation' parameter indirectly. It does not explain 'message' (likely the main text) or 'context' (possibly additional info). The description offers partial guidance at best, leaving most parameters undocumented. This is below the baseline 3 for 0% coverage, but the description does clarify the purpose of 'conversation,' earning a 3.

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: 'Report a bug, missing feature, or send feedback.' It uses a specific verb (report) and resource (bug/feature/feedback), which is clear even though it doesn't explicitly differentiate from siblings. However, siblings are mostly unrelated (authenticate, connect, marketplace, etc.), so it stands out sufficiently.

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—when reporting issues or feedback—but it does not provide explicit guidance on when not to use it or alternatives. The mention of 'Include the conversation array with recent messages for reproduction' gives some usage context but lacks exclusion criteria. Given the sibling list, there is no obvious alternative, so a moderate score is appropriate.

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 behavioral context beyond this by stating 'sem credenciais da plataforma' (no platform credentials needed), 'pague por consulta com crédito pré-pago' (paid per query), and the LGPD data-controller responsibility. These details inform the agent about authentication, cost, and legal implications, going well beyond the annotation cues.

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 paragraph that mixes essential query information with legal and financial disclaimers. It is reasonably concise at about 60 words, but it could be better structured to front-load the functional purpose before discussing payment and compliance details.

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 parameter, no output schema, and read-only annotations, the description provides substantial context: the authoritative nature of the source, the lack of credential requirements, the pay-per-query model, and LGPD compliance responsibility. It covers the main aspects an agent needs to know, though it could mention response characteristics or error conditions.

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 for the only parameter 'nfce', the description needed to compensate, but it does not explicitly explain what the parameter is or its expected format. The letter 'nfce' is mentioned in the tool name and description, and the parameter name is identical to the acronym, but there is no clarification about whether it's a key, number, or URL, nor any example or format hint.

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 this is a query ('consulta') for NFC-e data from SEFAZ SP, and it is described as accessing official Brazilian sources. While it lacks the explicit sibling-distinguishing language seen in higher-scoring examples, the tool name and description together leave little doubt about its function.

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?

There is no guidance on when to use this tool versus alternatives, nor any exclusion criteria or alternative tool references. The description focuses on commercial and legal caveats (pay-per-query, LGPD) rather than providing usage context or prerequisites.

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 read-only, idempotent, and non-destructive behavior. The description adds no additional context beyond that, so it meets the baseline but does not enhance transparency further.

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, clear sentence with no unnecessary words. It is well-structured and immediately understandable.

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 and lack of parameters or output schema, the description is sufficient. It could mention the return value format, but that is not essential for this trivial operation.

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, so the schema coverage is complete. The description does not need to explain parameters, and the baseline for zero-parameter tools is met.

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. It is specific and distinguishes itself from siblings like 'authenticate' or '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 does not explicitly state when to use it, but the purpose is self-evident for version checking. It is distinct from sibling tools, so no alternative is hinted, but it could benefit from a note like 'Use to verify compatibility or current environment status.'

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 safety profile is covered. The description adds meaningful behavioral context by specifying the returned state components (installed MCPs, connection status, accounts, catalog tool counts), which goes beyond the bare annotations. It does not contradict 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, front-loaded sentence that immediately states the primary purpose, followed by a concise list of returned elements. Every word earns its place with no redundancy or 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?

Given the tool has no parameters, no output schema, and simple informational scope, the description fully covers what the agent needs to know: what state is returned and the categories of data included. The presence of strong annotations further reduces the need for extra safety caveats.

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 effectively 100% (empty properties object). Per the baseline for tools with no parameters, a 4 is appropriate since there are no parameter semantics to explain and the description does not need to compensate for missing schema detail.

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') with a well-defined resource ('current toolkit state') and elaborates on exactly what is included: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly differentiates it from siblings like show_version, which presumably only reports version 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 the tool is for inspecting overall toolkit state, but it does not explicitly state when to use this over alternatives like connect, authenticate, or show_version. There are no exclusions or alternative recommendations, so the usage context is only implied by the nature of the tool.

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