Receita Federal NFS-e: Notas Emitida (Detalhes)

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

Annotations already declare idempotence and non-destructiveness; the description adds browser login mechanics, JWT handling, and persistent vs session behavior. It does not cover error cases or side effects, but adds meaningful context beyond 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?

Three dense sentences with no filler; each clause covers a distinct aspect: browser flow, permanent config, and session usage. The core action is front-loaded.

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 no output schema, the description covers invocation modes and the expected user flow. It lacks explicit success/failure details, but is sufficient for the tool's 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?

Despite 0% schema coverage, the description fully explains the optional token parameter as a JWT pasted from the browser for session login, and the no-args alternative for retrieving the link. This fully compensates for 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 identifies the tool as an MCP.AI authentication flow for IDE agents, specifying browser login, access token retrieval, and both permanent and session-only configuration. This makes it distinct from siblings like 'connect' or '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 explicitly contrasts the recommended permanent setup via config header with the session-only paste flow, and tells the agent exactly when to call with a token vs no args. This provides actionable decision 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, idempotentHint=true, and destructiveHint=false, establishing a safe read operation. The description adds behavioral detail about the authenticated flag and pending array, enriching transparency 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?

Two sentence description, front-loaded with what it returns, then provides state-based details. No wasted words.

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 and no output schema, the description fully covers the two relevant states (all connected vs missing credentials). It is complete for its simplicity.

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 zero parameters, so the baseline is 4. The description correctly focuses on output behavior without needing parameter details. No additional parameter semantics are 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 it returns connection status and URLs, and specifies the behavior in two cases: all providers connected vs missing credentials. This distinguishes it from sibling tools like 'authenticate' which handles authentication flow.

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 connection status but does not explicitly contrast with siblings or state when not to use. It gives context about scenarios (connected vs missing credentials) but lacks explicit when/when-not 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?

No contradiction with annotations (readOnlyHint=false correctly matches the described writes; destructiveHint=false is consistent). The description adds valuable behavioral context beyond annotations: writes require workspace owner/admin, invoke runs one-off without bloating the toolkit, and failed invocations return connect/checkout links requiring user action before retry. Minor gap: no detail on response formats or side effects of resume.

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?

Every sentence carries decision-relevant content, and the opening sentence front-loads the primary purpose. However, it is delivered as one dense unbroken paragraph covering two distinct domains (MCP operations and the prompt library), which hurts scannability. Appropriate length for the complexity, but structure is lacking.

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 23-parameter, 14-action tool with zero schema descriptions and no output schema, the description is remarkably complete on workflow logic — covering the install/invoke distinction, auth requirements, billing links, and the prompt-library sub-domain. The main completeness gap is parameter-level documentation for the ~10 params not covered by the narrative, and it could describe typical result shapes of search/describe.

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 and 23 parameters, the descriptive burden is high. The description compensates for the core operational params (action routing, mcp_id/tool_id/arguments via the search→describe→invoke narrative) but leaves many params unexplained (limit, immediate, tier_slug, conversation, prompt_targets, cancel_comment, report_context, request_details). It maps the flow-level params but not the long tail.

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 official mcp.ai marketplace' — a catalog plus execution layer, and enumerates its 14 actions with concrete examples ('find an MCP that does X', 'consulta um CPF'). Purpose is specific and distinguishes it from siblings like authenticate/connect/toolkit_info, though as a multi-action dispatcher it lacks a single clean verb+resource.

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?

Exceptional guidance: it prescribes the core flow (search → describe → invoke), explicitly contrasts invoke vs install ('prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT'), names the credential/checkout retry loop, and maps subscriber functions (subscribe/cancel for billing, report_bug, request_mcp). This is textbook when/when-not decision support.

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?

Beyond annotations (readOnly, idempotent), the description adds value by disclosing cost per query, lack of platform credentials, and LGPD data controller responsibilities. It does not contradict annotations and provides meaningful operational 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 moderate-length paragraph that includes operational and legal disclaimers (payment, LGPD) which, while informative, dilute the core purpose. It front-loads the purpose but the legal boilerplate could be trimmed without losing essential tool guidance.

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?

With 6 parameters, no output schema, and zero schema coverage, the description should explain parameter usage and response expectations. It does neither, leaving the tool under-specified for safe invocation, especially regarding the meaning of login/credential parameters.

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 the description provides no explanation for any of the 6 parameters (chave, login_cpf, etc.). The required 'chave' and credential-related fields are left entirely unexplained, so the description fails to compensate for the 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 clearly states the tool queries details of issued NFS-e (electronic invoices) from Receita Federal, using the verb 'consultar' (query) with a specific resource. However, it doesn't explicitly distinguish from potential sibling NFS-e query tools, though none are present in the listed siblings.

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 about payment (prepaid credit), hosting, and data source officiality, implying usage for querying official tax data. But it lacks explicit guidance on when to use this tool over alternatives or any prerequisites beyond payment.

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 provide safety signals (idempotentHint=true, destructiveHint=false) but the description adds little behavioral context. It explains that the conversation array is needed for reproduction, but does not disclose whether the report creates a permanent entry, sends data externally, or what the user should expect after calling the 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 one concise sentence that front-loads the core purpose and then complements it with a specific, actionable detail. No filler or redundant content.

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 tool is relatively simple, and the description covers the main use case. However, missing parameter semantics and lack of information about the conversational payload format mean the description is only minimally sufficient for a 3-parameter 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?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It only hints at the 'conversation' parameter by mentioning the conversation array. The 'message' and 'context' parameters are not described in the text, leaving the agent to infer their meanings from the schema alone.

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 specific verbs ('Report', 'send feedback') and clearly defines the resource/action scope as bugs, missing features, and feedback. It distinguishes itself from all sibling tools, which are unrelated to 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?

It states when to use the tool: 'Report a bug, missing feature, or send feedback.' It also gives a concrete usage tip about including the conversation array for reproduction. It does not mention alternatives or exclusions, but such guidance is not necessary given the distinct purpose.

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, idempotentHint, and destructiveHint false, so the safety profile is well-covered. The description adds no additional behavioral context beyond what the annotations provide, but it does not contradict them either.

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 immediately conveys the action and scope. There is zero wasted text, and it is front-loaded.

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 low complexity (no params, no output schema, no nested objects), the description is entirely adequate. It clearly states what information is returned (versions) and needs no further elaboration.

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 them. The description correctly confirms it is a no-argument call, which aligns with the baseline of 4 for 0-parameter tools.

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: showing the current MCP platform and adapter versions. It uses a specific verb ('Show') and identifies the resource ('MCP platform and adapter versions'), which distinguishes it from potential siblings like toolkit_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 usage (when you need version information) but does not explicitly mention alternatives or when not to use it. Given the simple nature of the tool and that it has no parameters, the lack of explicit guidance is acceptable but not ideal.

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 restate safety. It adds value by detailing exactly what information is returned (installed MCPs, connection status, accounts, number of tools). 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?

The description is a single, concise sentence that front-loads the purpose and lists all key return elements. No redundant words or unnecessary 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?

Given the tool has no parameters flags and no output schema flag, the description sufficiently explains what the tool returnsaine. Annotations cover read-only/idempotent behavior, so nothing is missing. The tool is simple and the description 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?

With zero parameters)Skip the schema is trivially covered (100% coverage). Since there are no parameters, the description has nothing to add about parameter semantics; the baseline 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 returns the current toolkit state, enumerating specific contents (installed MCPs, connection status, accounts, catalog tool counts). The verb 'returns' and resource 'toolkit state' are specificament, distinguishing it from sibling tools like authenticate or connect which perform 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 implicitly conveys when to use this tool: to inspect the current toolkit state. It doesn't explicitly mention when not to use it or alternative tools, but given the simplicity (zero parameters) and clear purpose, the usage context is obvious. Sibling tools are action-oriented, so the contrast is apparent.

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