Receita Federal NFS-e: Notas Recebida (Detalhes)

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

The description discloses key behaviors: it distinguishes between permanent (non-expiring) and session-only connections, implying side effects related to session persistence. It does not explicitly mention error cases or invalid tokens, but it provides sufficient transparency for common use. The annotations indicate idempotent and non-destructive, which aligns with the described 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 concise yet informative, consisting of two sentences that logically flow from the login process to the different authentication methods. It avoids unnecessary details while covering all essential usage aspects.

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 single optional parameter and no output schema, the description provides complete context: it explains how to use the tool, what the token represents, and the outcomes of different calls (link vs. authenticated session). It covers all necessary information for an agent to invoke it 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 schema only defines a `token` string, but the description adds crucial semantic meaning: it explains that the token is a JWT and that it is optional (no args to get link). This significantly enhances understanding of the parameter beyond the basic type 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 clearly states the tool's purpose: authentication. It explains that the user logs in, copies the access token, and then uses it to authenticate either by adding it to config or pasting it. The verb 'authenticate' and the resource (access token) are specific, and it distinguishes from sibling tools like 'connect' by focusing on credential management.

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 instructions: how to obtain the token (log in, copy), and two ways to use it (add to config for permanent connection or paste for session-only). It also mentions that calling with no args returns a link, clarifying the optional parameter behavior. This is clear and actionable.

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 behavioral detail beyond the annotations: it explains the authenticated state, the pending array, and the connect URLs returned in the missing-credentials case. The annotations already declare readOnlyHint=true and destructiveHint=false, and the description's read-only semantics are consistent with them, so there is no contradiction.

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 sentences, front-loaded with the core function, and every clause conveys needed conditional behavior. No filler or repetition beyond what is useful.

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 parameterless read-only status tool, the description is complete: it describes normal connected state and degraded missing-credentials state, and no output schema pushes the burden onto the description. A small explicit 'use this to check connectivity' sentence could be nice, but it is already sufficient given the 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?

The tool has zero parameters and schema coverage is 100%, so the parameter burden is minimal. With no parameters to explain, the description's focus on returned value semantics is appropriate and fully 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 uses a specific verb ('Returns') with a clear resource ('connection status and URLs'), and the conditional outcomes ('authenticated:true and empty pending[]' vs 'connect_url') make the tool's scope unambiguous. It effectively distinguishes this status-checking tool from the sibling '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?

The description gives clear situational context: when providers are connected, what to expect; when credentials are missing, what URLs are returned. It does not explicitly name alternatives or say 'use this instead of authenticate', so it lacks the strong when/when-not differentiation that would earn a 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?

The description goes far beyond annotations (readOnlyHint=false, destructiveHint=false) by disclosing that invoke runs one-off without bloating the toolkit, may return connect or checkout links, and that writes require owner/admin. It also segments the prompt library as a separate concern, providing comprehensive 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 dense paragraph but exceptionally information-dense, with a logical flow from core flow to key behaviors to requirements to prompt library. It could benefit from bullet points, but all content is purposeful and front-loaded with the most important differentiators.

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 23 parameters, no output schema, and 14 distinct actions, the description is remarkably complete: it explains the end-to-end flow, permission requirements, fallback mechanisms for auth and payment, and segues into the prompt library. It covers all major use cases and edge cases, leaving little ambiguity for an agent to misuse it.

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 23 parameters and 0% schema description coverage, the description carries full responsibility for explaining parameters. It mentions major ones (action, query, mcp_id, tool_id, arguments, prompt_*), but leaves many unexplained (e.g., immediate, tier_slug, conversation, request_details, cancel_reason). While the action enumeration and core parameters are covered, incomplete documentation of the rest leaves agents guessing on advanced 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 identifies the tool as the official mcp.ai marketplace, governing both discovery and execution of MCPs. It enumerates distinct actions (search, describe, invoke, install, etc.) and explains the core flow, distinguishing it from sibling tools like authenticate and connect. The verb 'marketplace' plus the detailed breakdown leaves no ambiguity about what the tool does.

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 when-to-use guidance, such as preferring invoke for one-off usage and install for permanent additions, and clarifies that invoke works even without installation. It also handles edge cases like auth and wallet links, and references list_tools for current callable tools, giving clear decision criteria among 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about payment (pre-paid credits) and LGPD responsibilities, but does not explain authentication behavior (e.g., need for login credentials or certificates) or what happens after a query, leaving some gaps.

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 that efficiently convey purpose, payment model, and legal compliance. It is not overly verbose, but the LGPD sentence is somewhat tangential; overall it is well-structured and front-loaded with the core 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?

Given the tool's complexity (6 parameters, no output schema), the description is insufficient. It does not describe expected return data, authentication flow, or how parameters like login_cpf relate to the 'official source' query. The payment and legal notes are helpful but do not fill the gap of operational details.

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 must explain all six parameters but does not. It only mentions 'chave' implicitly as a key, and ignores login_cpf, login_cnpj, login_senha, pkcs12_cert, and pkcs12_pass entirely, leaving the agent with no semantic understanding of required 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 clearly states the tool queries details of received NFS-e (Notas Recebida) from the official Brazilian federal source, using the verb 'consultar' and the resource 'NFS-e'. It distinguishes itself from generic siblings like 'authenticate' and 'marketplace' by specifying the domain and purpose.

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 querying official NFS-e data but provides no explicit when-to-use guidance or alternatives. It mentions payment and LGPD compliance but does not clarify when this tool should be selected over others, relying on the name for 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?

The description adds minimal behavioral context beyond annotations. It mentions including the conversation array, but does not disclose side effects (e.g., whether it sends an email, stores a record) or any potential consequences of calling the tool. The annotations already indicate non-destructive and idempotent behavior, so the description does not contradict them, but it could be more transparent.

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 information. It is well-structured and directly to the point.

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 tool's purpose and gives a hint about one parameter, but it lacks elaboration on parameter usage (especially 'context'), potential side effects, or any output expectations. Given the simple schema, it is adequate but not fully 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?

With 0% schema description coverage, the description must compensate. It provides meaning for the 'conversation' parameter ('recent messages for reproduction'), but does not explain 'message' or 'context'. This partial coverage leaves significant ambiguity.

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.' The verb 'report/send' and the objects (bug, feature, feedback) are specific and distinct from sibling tools 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 gives a practical instruction ('Include the conversation array with recent messages for reproduction') but does not explicitly outline when to use this tool versus alternatives. It implies bug reporting but lacks comprehensive usage scenarios.

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, covering the safety profile. The description adds no extra behavioral details (e.g., return format), but it is consistent with annotations. Given the annotations, this is adequate though minimal.

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 with no redundancy. It immediately conveys the function and is front-loaded, containing every necessary piece of information for a trivial 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 zero-parameter tool with no output schema, the description is complete enough: it tells the user what information is returned (platform and adapter versions). It doesn't specify the data type, but that's not critical for a simple version tool. It adequately covers the tool's behavior.

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 there is nothing to describe beyond the schema. The schema itself has no properties, and the description doesn't attempt to add param info. With no parameters, this is the baseline for a successful description.

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: 'Show the current MCP platform and adapter versions.' It uses a specific verb ('Show') and resource ('MCP platform and adapter versions'), distinguishing it from sibling tools like authenticate or connect, which have 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?

Although no explicit 'use when' or alternatives are mentioned, the purpose is self-evident for a version-info tool. Sibling tools are contextually different, and this description implies its usage—when you need version information. It provides clear context without needing exclusions.

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 value by specifying exactly what state information is returned (installed MCPs, connection status, accounts, tool counts), which is beyond the annotations and provides useful behavioral detail. 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 sentence, front-loaded with the main purpose ('Returns the current toolkit state') and followed by a concise enumeration of returned data. Every word earns its place with no 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 read-only info tool with no parameters and no output schema, the description fully explains the tool's function and return content. The annotations cover safety, and the siblings are all action-oriented, making this complete for its purpose.

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, the description appropriately needs no parameter explanation. The empty schema is fully covered (100%), 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 returns the current toolkit state and enumerates specific elements: installed MCPs, connection status, accounts per MCP, and catalog tool counts. It distinguishes itself from siblings like authenticate or connect, which are action-oriented, by focusing on informational retrieval.

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 that this is a read-only state-checking tool, implying use for initialization or diagnostics. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a full 5.

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