SEFAZ ES: NFC-e

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

Annotations already indicate idempotent and non-destructive behavior. The description adds context about the two modes but does not mention potential side effects or error cases, which is acceptable for a simple 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?

The description is slightly verbose but well-structured, covering both usage modes without unnecessary fluff. All sentences contribute to understanding.

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?

It explains the input and the two authentication paths, but does not specify the return format when the link is returned or what happens after authentication. Given no output schema, this is a minor gap.

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 single 'token' parameter is optional (required=0) and the description clarifies its use: providing it authenticates, omitting it returns the link. This adds meaning beyond the bare schema.

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 that the tool handles authentication, distinguishing it from sibling tools like 'connect' and 'marketplace'. It specifies two modes: permanent configuration and session-only token.

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 instructions for both use cases: adding a token to config for permanent access, or pasting a token for session-only access. Also explains the no-args option to get the link. Clear but does not explicitly mention when not 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, idempotentHint, and destructiveHint=false. The description adds valuable behavioral detail: it explains the exact return values (authenticated:true and empty pending[] when connected, and connect_url when credentials are missing), which is not present in 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 two sentences, front-loads the main purpose, and contains no filler or redundant information. Every sentence adds meaningful 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 tool with no parameters and no output schema, the description is fully complete. It covers both relevant scenarios (connected vs. missing credentials), making it sufficient for an agent to select and invoke the tool 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 tool has zero parameters, so the baseline is 4. The description does not need to explain parameter details, and it does not repeat any schema information.

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 'Returns' and clearly identifies the resource as 'connection status and URLs.' It distinguishes the tool from siblings like 'authenticate' (which handles authentication actions) by focusing on status reporting rather than performing authentication.

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 the expected output in different states (all providers connected vs. credentials missing). It does not explicitly mention when to use alternatives, but the context is clear enough for an agent to know this is the status-checking 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 only provide high-level hints (readOnlyHint=false, openWorldHint=true). The description adds crucial behavior: invoke works even if the MCP isn't installed, writes need workspace owner/admin, credential/checkout links are returned, and search/describe flag installed_in_toolkit vs installed_in_workspace. This is substantial beyond the annotations and no contradiction is present.

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, covering a huge array of behavior; much of it is valuable, but the one-block wall of text makes it harder to parse. Labeling ('KEY:', 'Core flow:') helps front-weight important ideas, but more structure, such as action lists or bullets, would greatly improve scannability. There is not much wasted content, but the organization is moderate.

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 enormous surface area (23 params, multiple action modes, no output schema), the description is unusually thorough: it explains search/describe/invoke/install, billing, owner-admin restrictions, prompt-library flows, shared links, and retry semantics for checkout. However, a few action-specific behaviors (resume, conversation, immediate, tier_slug) remain under-specified, so it is nearly complete but has clear 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?

The input schema has 23 parameters with 0% description coverage, so the prose carries a heavy burden. The description does clarify many parameters indirectly through the action flow (e.g., tool_id, arguments, mcp_id, prompt_slug, prompt_body, cancel_reason), but several parameters remain underspecified: limit, conversation, immediate, tier_slug, and resume are not clearly explained. It partially compensates but does not fully compensate for no 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 explains that this is the mcp.ai marketplace catalog, and clearly distinguishes multiple action flows (search, describe, invoke, install, list_tools, billing, prompts). It names the main verbs and resources, and makes the tool's role clear even though it is an aggregator-style tool with many operations.

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 one-off use, use install only to make an MCP permanent, and states that list_tools lists currently callable tools. It also separates the MCP marketplace flows from the prompt library flows, so the agent knows when to use different actions and when to avoid installing an MCP.

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=false, destructiveHint=false, and idempotentHint=true. The description adds useful reproduction-related context (conversation array), but does not disclose side effects, destination, or confirmation behavior.

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 short sentences, front-loaded with the core purpose, and every sentence adds value. No filler or redundant restatement.

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 no output schema and 0% parameter description coverage, the description leaves message/context semantics and expected return behavior unstated. It covers the basic purpose but is not fully complete for autonomous use.

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 only explains the conversation parameter; the required message parameter and optional context parameter are left undescribed, leaving agents without enough meaning for all inputs.

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 ('Report') and identifies the exact resource: bugs, missing features, and feedback. It clearly distinguishes this tool from siblings like authenticate, connect, and marketplace.

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 provides clear contexts for use: reporting a bug, missing feature, or feedback, and instructs to include the conversation array for reproduction. It does not mention explicit alternatives, but no sibling tool serves this function.

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 valuable context: the data is not confidential, it is the same available to citizens, and the client is responsible for LGPD compliance. It also explains the payment mechanism (prepaid credits). These details go beyond the annotations and provide useful behavioral insight.

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 the core purpose ('SEFAZ ES: NFC-e, consulta em fonte oficial') and then adds practical details. It is a single paragraph of about 50 words, with no redundant filler. It is concise and well-structured, though the legal and payment notes could be trimmed without losing essential 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 read-only tool with one parameter, the description covers the data source and legal aspects but does not specify what the response contains or any required input format. Since there is no output schema, the description should at least hint at the expected return value (e.g., the NFC-e details). The absence of this information leaves a gap for the agent.

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 a string with zero schema description coverage. The description mentions 'NFC-e' in the purpose but does not explain the expected format (e.g., a key, a number, a URL). It gives a hint that the parameter is likely the NFC-e identifier, but this is not explicit enough for an agent to construct correct input. The description fails to compensate for the lack of schema documentation.

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 tool consults NFC-e data from the official SEFAZ ES source. It uses the specific verb 'consulta' and identifies the resource (NFC-e), distinguishing it from sibling tools like authenticate or marketplace, which have different purposes.

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 context on when to use the tool (for NFC-e consultation from official sources) and mentions the payment model, but does not explicitly discuss alternatives or when not to use it. Since there are no closely related sibling tools, the absence of explicit exclusions is acceptable, but the guidance is not fully explicit.

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 safe read behavior is covered. The description adds that it displays both platform and adapter versions, which provides some context beyond annotations, but there's no mention of output format or any potential prerequisites.

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 wasted words. It front-loads the purpose effectively and is appropriately concise for a zero-parameter 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?

For a simple read-only version tool, the description is adequate: it states what is displayed and the annotations cover safety. It doesn't explain the return format, but given the simplicity and lack of output schema, this is not a major gap. It could mention that it's a quick informational tool, but overall it's minimally 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, so schema coverage is 100% by default. The description doesn't need to explain parameters, hence baseline 3 is appropriate, as there's no additional parameter meaning to add.

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 states the tool shows current MCP platform and adapter versions, which is specific enough for a version display tool. It doesn't explicitly distinguish from siblings like toolkit_info, but the scope is clear without being a tautology.

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 checking version information, but no explicit guidance on when to use this versus sibling tools like toolkit_info. Given the simple nature and zero parameters, the implied usage is adequate but could name an alternative.

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 safe, non-mutating behavior is known. The description adds useful content details (MCPs, status, accounts, tool counts) but doesn't disclose additional behaviors such as whether the state is real-time or if errors occur with no MCPs installed. With annotations covering the safety profile, this is adequate but not 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 a single sentence that front-loads the action and resource, then enumerates key data points. Every part adds value, with no filler or 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 simple zero-parameter read-only tool with no output schema, the description fully conveys what the tool does and what it returns. Annotations provide safety context. No critical information is missing.

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 baseline is 4. The description doesn't need to add parameter details since there are none, and the schema is empty.

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') and clearly names the resource ('current toolkit state') with enumerated details: installed MCPs, connection status, connected accounts, and catalog tool counts. This distinguishes it from sibling tools like authenticate/connect (which are actions) and show_version (likely version info only).

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 makes its use case clear by listing the state information it provides, implying when to call it (e.g., to assess toolkit connectivity or MCP inventory). However, it does not explicitly mention when not to use it or point to alternative tools, so it stops short of full guidance.

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