SEFAZ AM: NFC-e Completa

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

Annotations already declare idempotent and non-destructive, but description adds meaningful context: two modes (no args returns link, token args logs in) and the concept of permanent vs session-only. 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?

Three sentences with no fluff, but the opening 'MCP.AI for IDE agents' is slightly awkward and could be streamlined. Information is front-loaded and each sentence 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?

For a simple single-param tool with no output schema, the description covers the main behavior (link retrieval and session login) and even mentions the config alternative. It doesn't explain return format or error cases, but these are not critical.

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%, but description fully explains the 'token' parameter (paste here for session), and states the no-args case (get link). This is excellent compensation for the lack of schema descriptions.

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 action (log in, copy access token) and resource (MCP.AI for IDE agents). It distinguishes from siblings by focusing on authentication, but could be more explicit as an 'Authenticate' tool.

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 usage guidance: best practice (config header for permanent connection) and alternative (paste token for session-only). Does not directly compare to sibling tools like 'connect', but gives clear when-to-use 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=true, idempotentHint=true, and destructiveHint=false, so the description only adds context about the return format (authenticated, pending, connect_url). This is some added value beyond annotations but is not extensive; it doesn't mention rate limits, security, or any unexpected behavior. 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?

Description is two sentences, efficient, and directly states the purpose and two key conditional outputs. No unnecessary fluff, front-loaded with purpose.

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?

Even without output schema, the description explains the two main outcome shapes. It covers connection status and URLs, and mentions pending[]. For a simple stateless read-only tool, this is fairly complete. However, it could specify the exact structure of the returned object (e.g., fields) but the given scenarios suffice.

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?

Tool has zero parameters, so baseline is 4. The schema already fully covers the lack of parameters; the description does not need to add parameter semantics.

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, which is specific verb+resource, but doesn't explicitly contrast with sibling tools like authenticate. It implies the purpose but leaves the agent to infer when to use it over alternatives.

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 conditional scenarios (when all providers are connected vs. when credentials missing) that help the agent understand behavioral expectations, but it does not explicitly state when to use this tool instead of siblings like authenticate or show_version. No explicit exclusion or alternative is mentioned.

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 into significant detail about behaviors not covered by annotations, such as that invoke works even when MCP is not installed, returns connect links for credentials, and checkout links for payment. It also notes that writes require workspace owner/admin. The annotations only provide generic hints, so this description adds substantial behavioral 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 long paragraph with dense information about many actions. While it covers necessary details, it could be structured with bullet points or sections for better readability. It is verbose but front-loaded with the core flow, so it earns a middle score for structure.

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 (23 parameters, multiple actions, no output schema), the description is remarkably complete. It explains the lifecycle of using the marketplace, including discovery, invocation, installation, billing, and prompt library, covering scenarios like authentication and payment. It addresses the main usage paths adequately.

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%, and there are 23 parameters, so the description compensates by explaining the key parameters indirectly through the action flow (e.g., action, mcp_id, tool_id, arguments, prompt_slug, prompt_vars). It provides meaning for the core actions and their typical inputs, which is essential given the lack of schema-level descriptions.

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 mcp.ai marketplace, covering both discovery (search/describe) and execution (invoke), along with prompt library functions. It distinguishes itself from siblings by providing a comprehensive overview of its multiple 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?

The description provides explicit guidance on when to use specific actions, such as 'install only to make an MCP PERMANENT' and 'prefer invoke for a single/occasional use', and mentions alternatives like list_tools for currently callable tools. However, it doesn't explicitly contrast with every sibling, but the main context is well covered.

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=false, destructiveHint=false, and idempotentHint=true, covering basic safety and side-effect expectations. The description adds value by noting the need to include the conversation array for reproducibility, which hints at what the tool expects. It does not disclose internal processes (e.g., sending data externally), but given the annotations, a 3 is appropriate as it adds some context without being rich.

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, front-loaded with the purpose and including a critical instruction. Every word earns its place; there is no redundancy or irrelevant detail. It is an exemplary model of brevity.

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 three parameters and no output schema, the description covers the essential purpose and key usage detail (conversation for reproduction). It is sufficiently complete for an agent to understand how to invoke it correctly, although it does not mention what constitutes a successful submission or any response format. Given the tool's low complexity and existing annotations, this is 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 input schema has 0% description coverage, so the description must compensate. It explicitly mentions the 'conversation' parameter and implies that 'message' holds the main content, but it omits any explanation of 'context.' Since only two of three parameters are addressed, it partially aids understanding but does not fully cover the schema. This warrants 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.' This uses a specific verb ('Report') and resource (bug/feature/feedback), and it distinguishes itself from sibling tools like authenticate, connect, and marketplace. The purpose is unambiguous and immediately understandable.

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 or when not to use it. It provides some usage context by instructing to 'Include the conversation array with recent messages for reproduction,' which implies the tool is for reporting issues with context. However, lacking explicit exclusions or alternative guidance, it falls short of a 4 or 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?

Annotations already declare read-only and idempotent behavior. The description adds meaningful context beyond annotations: the tool is platform-hosted, uses prepaid credits, pulls from official Brazilian sources, and imposes LGPD responsibilities—information that informs the agent about side effects and compliance.

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 and front-loaded with the core purpose. While it contains legal boilerplate, the length is still reasonable and no extra fluff is present.

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 single-parameter tool, the description fails to explain the parameter or expected input, and omits what 'Completa' means or what the response contains. Annotations help with safety but not with usability.

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 does not compensate by explaining the 'nfce' parameter. A critical omission—there is no hint about expected format (e.g., 44-digit key) or any input constraints, making correct invocation guesswork.

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 indicates a query operation ('consulta') for NFC-e data from SEFAZ AM, naming a specific resource. However, it does not differentiate from sibling tools, as none of the siblings perform similar functions, and the phrase 'Completa' is left undefined.

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 NFC-e documents and mentions pay-per-query, but provides no explicit when-to-use guidance or alternatives. The legal/payment disclaimers dominate over practical usage 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 declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to repeat that. It adds minimal extra behavioral context (only that it returns current versions). There is 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 direct and front-loaded. It contains no filler or redundant 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 simple, zero-parameter tool with safe annotations, the description adequately conveys the purpose. It doesn't explain the output format, but that is not critical for a version query. It is nearly complete for this simple case.

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). No additional parameter semantics are needed, so the baseline score 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 clearly states the tool's function with a specific verb 'Show' and a specific resource: 'current MCP platform and adapter versions'. This distinguishes it from sibling tools like 'toolkit_info' which likely provides broader 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. The description simply states what it does without mentioning any context, situations, or comparisons with 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description goes beyond by specifying what kind of state is returned (installed MCPs, connection status, accounts, catalog tool counts), adding behavioral context about the tool's scope without conflicting with 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 single sentence that leads with the primary action and then lists the specific contents in a comma-separated list. Every word adds value; there is no filler or redundancy. It is appropriately sized for a zero-parameter informational 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 (no parameters, no output schema), the description fully explains what the tool returns and in what detail. It covers all major aspects a user would need to know: the general purpose and the specific items contained in the state. There are no missing pieces.

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 already fully covers parameters. The description does not need to add parameter semantics, and the baseline for 0 params is 4. The description correctly omits any parameter-related details, and no additional meaning is required.

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 'Returns' and the resource 'current toolkit state', then enumerates specific contents (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from sibling tools like 'connect' or 'authenticate' which are action-oriented, while 'toolkit_info' provides a read-only overview.

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 context (checking the state of installed MCPs and connections) but does not explicitly state when to prefer this over alternatives, nor does it mention any exclusions. It's adequate for a simple informational tool but lacks explicit guidance on when not to use it (e.g., when you need to perform an action).

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