SEFAZ MT: NFC-e

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

While the annotations already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false, the description adds valuable context beyond these fields. It explains the two distinct login paths (config-based vs. session-only), the security implication of 'non-expiring' tokens, and the behavior of calling with no arguments (get link) versus with a token (complete login). It conveys the idempotent nature by implying repeat calls are safe.

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 61-word run-on sentence that combines context, setup instructions, and usage examples. While it front-loads the core context ('MCP.AI for IDE agents') and gives clear options, the lack of paragraph breaks or stronger structure makes it dense. It could be split into two or three cleaner sentences without losing meaning.

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 1 optional parameter and no output schema, the description comprehensively covers the essential user flows: getting the login link and completing login with a pasted token. It explains both authentication methods (config vs. session) and the implications of each. It could potentially mention error cases or what happens on invalid tokens, but for the low complexity of this tool, it is 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?

With 0% schema description coverage, the description carries the full burden of explaining the token parameter. It states: 'call with { token: "<jwt>" } after the user pastes, or with no args to get the link,' correctly explaining the token's purpose and implying it is optional. While it explains what the token does, it could be slightly clearer about the JWT format details, but overall the guidance is sufficient for an agent.

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 explains the authentication purpose with a specific flow: 'log in in the browser, copy the access token.' It distinguishes itself from sibling tools like 'connect' by describing a specific browser-based login mechanism for MCP.AI, and the 'no args to get the link' phrasing clarifies the tool's primary entry point. However, 'MCP.AI for IDE agents' is a somewhat awkward and ambiguous opening that doesn't immediately state the 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 provides clear usage direction: 'Best: add it to this server's config... for a permanent, non-expiring connection. Or paste it here for a session-only login.' This explicitly compares the two authentication methods and recommends one over the other. However, it doesn't explicitly mention when not to use the tool or reference alternatives like the connect sibling.

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 behavioral detail about the exact return states and URL fields, going beyond the annotations without contradicting them.

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 core purpose, and contains no filler or redundant information. Every clause adds meaningful detail about output states.

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 status tool with strong annotations, the description covers the main return states well. It does not explicitly describe partial connectivity or error behavior, but the mention of pending[] and the two stated conditions is sufficient for most selection and invocation purposes.

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 schema fully covers parameter semantics by definition. The description does not need to explain parameters, and it appropriately focuses on output behavior instead.

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, with specific output conditions (authenticated:true with empty pending[] when all providers are connected; connect_url and per-install URLs when credentials are missing). This distinguishes it from siblings like authenticate, which performs authentication rather than reporting status.

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 by describing the two relevant states: checking whether all providers are connected and retrieving connection URLs when credentials are missing. It does not explicitly name alternatives or state when not to use it, but the conditional behavior provides clear usage 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 are minimal (readOnlyHint=false, openWorldHint=true, destructiveHint=false) and provide no specific side-effect info. The description compensates by disclosing that invoke works even without installation, runs one-off, and may return connect/checkout links. It also notes that writes require owner/admin and that search/describe flag installation status. This adds meaningful behavioral context beyond annotations, though it does not cover every edge case.

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 long single paragraph, dense with information. It front-loads the purpose but then lists many actions and concepts without clear structural breaks. It is efficient in that every sentence adds value, but it is not well-structured for quick scanning. For such a complex tool, a bit more organization (e.g., bullet points) would improve readability, but overall it is not excessive.

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 covers the main flow (search→describe→invoke) and explicitly differentiates invoke vs install, plus mentions the prompt library. However, it omits details on several actions (resume, uninstall, cancel details, request_mcp specifics) and does not explain parameters like limit, query, or prompt_* fields. With 23 parameters and no output schema, a more comprehensive description would be expected, but it covers the most critical usage patterns.

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%, so the description must explain parameters. It explains the 'action' enum semantics well (search, describe, invoke, etc.) and mentions some related params (mcp_id, tool_id, arguments) implicitly, but it does not describe the 23 parameters individually. Many params like limit, query, prompt_*, cancel_* remain unexplained. The description gives high-level flow but not parameter-level detail, which is a significant gap for a tool with 23 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 it is 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It specifies the core actions (search, describe, invoke, install) and distinguishes from siblings like authenticate and report_bug by focusing on discovery and execution of MCPs. The purpose is specific and well-defined.

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 when to use invoke vs install ('prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT'), and clarifies when to use list_tools ('lists what is callable right now'). Also explains that subscribe/cancel handle billing and that writes require workspace owner/admin. This is a clear usage guide with 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 indicate idempotentHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds valuable behavioral context by specifying that the conversation array should be included for reproduction, which is not inferable from annotations or schema. However, it doesn't disclose what happens after the report (e.g., ticket creation), but the annotations relieve some of that burden.

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 purpose and ends with a practical instruction. Every word earns its place; there is 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?

For a simple feedback-reporting tool with 3 parameters, one required, and no output schema, the description covers the core purpose and gives a key usage hint about the conversation parameter. It omits details like response behavior, but the annotations and schema fill in the safety and required-field gaps. Overall, it is sufficiently complete for an agent to select and invoke 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?

Schema description coverage is 0%, so the description must compensate. It clarifies the 'conversation' parameter by instructing the user to include recent messages for reproduction, which adds meaning beyond the raw schema. However, it doesn't mention 'context' at all, and it uses the phrase 'conversation array' while the schema defines the parameter as a string (presumably serialized JSON), which could cause mild confusion. 'message' is self-explanatory.

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 the specific verb 'Report' with explicit object types ('a bug, missing feature, or send feedback'), making the tool's purpose unmistakable. It clearly distinguishes itself from sibling tools like authenticate, connect, and marketplace, which serve entirely different functions.

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: use this tool whenever the user wants to report a bug, request a feature, or give feedback. While it doesn't explicitly state exclusions or alternatives, the sibling tools are unrelated and there is no competing feedback mechanism. It also gives a concrete usage instruction ('Include the conversation array with recent messages for reproduction'), which helps the agent decide when and how to invoke 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 and idempotentHint. The description adds value by explaining the authentication model (no platform credentials) and the payment per consultation, as well as clarifying that data is non-confidential and subject to LGPD control. This goes beyond the annotations without contradicting them.

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 sentences, front-loaded with the core purpose and followed by necessary operational details. No wasted words; every sentence contributes to understanding the tool's context and constraints.

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 a single parameter and no output schema, the description should clarify the expected input and return value. It mentions consultation of official data but omits the parameter format and any output description. It also lacks guidance on response structure or error handling, making the tool incomplete for agent use without additional inference.

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 string parameter 'nfce' with 0% schema description coverage. The description does not explain what format or value should be passed (e.g., NFC-e access key or number). It fails to compensate for the lack of schema documentation, leaving the agent without essential invocation details.

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 consultation for NFC-e from SEFAZ MT, an official source. The verb 'consultar' and resource 'NFC-e' are explicit, and the context 'fonte oficial' distinguishes it from unrelated 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 provides usage context: no platform credentials needed, prepaid credit required, and it accesses public official data. It implies when to use (for NFC-e queries) but lacks explicit instructions on prerequisites or exclusions. Since sibling tools are unrelated, this is a clear usage scope, though not exhaustive.

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 readOnlyHint: true, idempotentHint: true, and destructiveHint: false, fully covering the safety profile. The description adds no behavioral details beyond the purpose, which is acceptable but does not enrich the agent's understanding 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, concise sentence that front-loads the core purpose. No unnecessary words or details, earning a top score 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?

For a simple read-only tool with no parameters and no output schema, the description fully communicates what the agent needs to know. Combined with robust annotations, it is 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 tool has zero parameters, and the schema coverage is 100%. With no parameters to explain, the description has nothing to add; per the baseline for 0-param tools, a score 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's function: 'Show the current MCP platform and adapter versions.' It uses a specific verb ('Show') and specifies the resource (MCP platform and adapter versions), distinguishing it from siblings like authenticate, connect, and report_bug.

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 purpose sets clear context for when to use the tool (when version information is needed). It does not explicitly exclude any scenarios or mention alternatives, but given the tool's simplicity and the absence of overlapping siblings, this is adequate.

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, openWorldHint=false, idempotentHint=true, destructiveHint=false. The description adds specific output details (MCPs, connections, accounts, tool counts), which is useful context beyond the annotations. No contradictions.

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?

Single sentence, highly concise with clear structure listing what is returned.

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 info tool with no parameters and clear annotations, the description fully captures the output. It lacks explicit mention of when not to use or alternatives, but given the tool's simplicity, it's complete enough.

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)Skip, so all parameters are covered trivially. The description explains the output, which is sufficient.

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 function: returning toolkit state including installed MCPs, connection status, connected accounts, and tool counts. It uses a specific verb ('returns') and a concrete resource ('current toolkit state'), which distinguishes it from siblings like authenticate (auth flow) or report_bug (bug reporting).

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 (to inspect toolkit state) but does not explicitly compare to alternatives like show_version or explain when not to use it. Context is clear, but no explicit when/when-not guidance is provided.

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