Receita Federal NFS-e: Notas Recebidas

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

The description discloses behavioral traits beyond the annotations: it explains that a token can be stored permanently in config or used for a session-only login, and that calling with no arguments returns a link. It doesn't mention side effects like state changes, but the idempotentHint=true and readOnlyHint=false are consistent; no contradiction. The description adds clarity about the two modes of operation.

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 but quite detailed, covering multiple use cases without unnecessary fluff. It is front-loaded with the core purpose and then explains the two ways to authenticate. While not extremely terse, every sentence contributes meaningful context, and the structure is logical.

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 one optional parameter, no output schema, and no nested objects, the description covers all necessary aspects: how to use it, when to use each mode, and the meaning of the token. It is complete enough for an agent to correctly invoke the tool in all scenarios without additional information.

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 has zero description coverage for the single 'token' parameter, but the description compensates by explaining exactly what the token is (a JWT) and when to provide it ('after the user pastes') versus omitting it ('with no args to get the link'). This fully clarifies the parameter's meaning and usage.

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: authenticate for IDE agents by logging in and obtaining an access token. It specifies the action (log in, copy token) and the resource (MCP.AI). However, it does not explicitly distinguish from the sibling tool 'connect', so it lacks explicit differentiation, though the purpose is still clear.

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 guidelines: it explains the two main workflows (permanent connection via config header vs. session-only via pasted token) and exactly how to invoke the tool (with or without the token argument). It gives clear conditions for each use case and even recommends the best practice, satisfying the when-to-use requirement.

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. The description adds concrete behavioral details: it returns connect_url when credentials are missing, and empty pending[] when all providers are connected. This goes beyond the annotation metadata.

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 that are information-dense with zero fluff. Each sentence adds distinct value: first defines the tool's output, second explains the edge case behavior.

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 fully explains the tool's behavior for a simple status endpoint. It could theoretically mention response formats, but with no parameters, no output schema, and clear semantics from sibling names, the description is complete for its 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?

With 0 parameters and 100% schema coverage (trivially), the description's job is minimal. It doesn't need to document parameters. The baseline of 4 applies here since there are no parameters to describe.

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 behavior for different conditions. It distinguishes itself from siblings by being the status-checking tool, especially with sibling names like 'authenticate' and '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 for checking connection status, and the sibling context suggests it's a read-only health check. It doesn't explicitly exclude other tools, but the purpose is clear enough that an agent would know when to call it versus 'authenticate' or 'toolkit_info'.

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 reveals key behavioral traits beyond the annotations: one-off execution without toolkit bloat, connect/checkout links when auth or payment is required, installed status flags, permission requirements for writes, and how the prompt library differs from MCP execution. This adds meaningful context and does not contradict the supplied 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 dense and front-loaded with the core marketplace flow, followed by edge cases, permissions, and prompt-library functionality. No sentence is wasted, though it is a single long block that would be clearer with a short break for the prompt library section.

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 this is a large multi-action tool with no output schema, the description covers the main flows well: discover, describe, invoke, install, billing, permissions, and prompt library. It is not fully complete because it omits details about several actions like resume, and does not describe return shapes, but it is serviceable for common agent-facing usage.

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 and 0% schema-level description coverage, so the description carries a heavy burden for parameter meaning. It explains action, mcp_id, tool_id, query, maybe arguments and prompt slugs at a high level, but it leaves many parameters undocumented—conversation, tier_slug, prompt_targets, cancel_reason, request_details, report_context—so the agent is not given enough semantic grounding for the full action surface.

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 opens with 'official mcp.ai marketplace — the in-platform catalog of every MCP/tool', then names specific actions: search, describe, invoke, install, list_tools, subscribe/cancel, report_bug, request_mcp, and the prompt library. It clearly defines what the tool does and distinguishes its many operational modes from the sibling tools.

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 when-to-use guidance: 'invoke works even when the MCP is NOT installed', 'Use install only to make an MCP PERMANENT', and 'prefer invoke for a single/occasional use'. It also explains the auth/wallet fallback flow, that writes require owner/admin, and that request_mcp is for cases where nothing fits.

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 meaningful behavioral context beyond annotations: it discloses payment requirements (prepaid credit), that no platform credentials are needed, that the data is non-confidential and sourced from official Brazilian agencies, and assigns LGPD responsibility to the client. These details complement the read-only, idempotent, non-destructive 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 a single paragraph, ~50 words, and every sentence adds relevant information (purpose, hosting, payment, data nature, LGPD). It is not overly verbose, but it could be slightly more structured by separating core purpose from legal/payment notes. Overall, it is efficient and 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?

With 8 parameters lacking any descriptions, no output schema, and no examples or usage scenarios, the description is incomplete. It mentions the tool queries official NFS-e data but does not explain the login/certificate parameters, date ranges, pagination, or expected results. This is insufficient for an agent to invoke the tool correctly, especially with such a complex parameter set.

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 description coverage is 0%, and the description does not explain any of the 8 parameters (e.g., pagina, login_cpf, data_final, pkcs12_cert). Since the schema provides no descriptions and the tool description omits parameter semantics, the agent has no guidance on how to fill these fields, making the tool nearly unusable without external knowledge.

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: to query received NFS-e (Notas Recebidas) from the official Federal Revenue source. It specifies the resource (NFS-e), the action (consult), and the authoritative origin, which 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 context (official source, not confidential, LGPD responsibility, pay-per-query) but does not explicitly state when to use it versus alternatives or mention any prerequisites or conditions for use. It implies that it is for querying NFS-e received notes but lacks explicit guidance on when not to use it or what inputs are required.

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 convey that the tool is not read-only, is idempotent, and is not destructive. The description adds the context that including recent messages is useful for reproduction, but it does not disclose what happens after submission, e.g., whether a report is persisted or sent to developers.

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 primary purpose, and both sentences add meaningful information. 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 low-complexity tool with three parameters and no output schema, the description gives enough to select the tool correctly and understand the main reproduction hint. However, it leaves parameter semantics and return behavior unstated, so it is only 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?

Schema description coverage is 0%, so the description must compensate by explaining parameters. It only mentions the 'conversation' parameter and even mischaracterizes it as an 'array' when the schema defines it as a string. The required 'message' and optional 'context' parameters are not explained at all.

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 is specific and immediately distinguishes it from the unrelated sibling tools like authenticate, show_version, 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 explicitly lists when to use the tool (bug, missing feature, feedback) and gives a practical usage instruction: include the conversation array for reproduction. It does not mention alternatives or exclusions, but the sibling tools are unrelated enough that this is not a significant gap.

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 the tool as read-only, non-destructive, and idempotent. The description adds only the 'current' qualifier, which does not provide additional behavioral context beyond the annotations. The description is consistent with the annotations but does not enrich 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 a single, concise sentence that directly conveys the tool's purpose without any redundant or extraneous wording.

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 sufficiently explains what the tool does, but it does not specify the output format or structure. Since no output schema is provided, the description could be more informative about the return value, but the tool's simplicity makes the absence acceptable.

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 no parameters, so the schema coverage is fully vacuous. There is nothing to add in terms of parameter semantics, and the baseline score of 3 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: to show current MCP platform and adapter versions. The verb 'Show' and specific resource ('current MCP platform and adapter versions') precisely define the action, distinguishing it from unrelated sibling tools.

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?

While no explicit alternatives or when-not-to-use are mentioned, the tool's straightforward nature makes its intended usage obvious—users query it when they need version information. This implicit guidance is adequate given the simplicity of the 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying what state information is returned (installed MCPs, connection status, accounts, catalog tool counts), giving the agent an expectation of the response content without needing an output schema.

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 action ('Returns') and immediately lists the delivered information. Every clause adds useful detail, with no wasted words or repetition of schema/annotation data.

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 info tool with good annotations, the description is complete. It explains what the tool returns (installed MCPs, connection status, accounts, catalog tool counts), which is sufficient for an agent to invoke it correctly. No output schema exists, but the description enumerates the key components of the result.

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 zero parameters, so the baseline is 4. The description correctly implies no inputs are needed, and there is no parameter information to provide. The tool is a simple query with no configuration choices.

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 with a specific verb ('Returns') and resource ('current toolkit state'), and enumerates the exact contents (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from siblings like show_version, which likely only returns version info, and authenticate/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 implies the tool is for retrieving an overview of the toolkit's state, but it does not explicitly state when to use it over alternatives or mention exclusions. For example, it doesn't say 'use this to check connection status before calling authenticate' or contrast with show_version. Context is present but not explicit.

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