Receita Federal NFS-e: Notas Emitidas

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

The description adds behavioral context beyond annotations: it explains the login flow in the browser, the token's role, and the permanent vs. session distinction. It aligns with annotations (idempotent, non-destructive) and doesn't contradict them. It could have mentioned idempotency explicitly, but the description covers key 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 a single dense sentence but front-loaded with the core action. It's efficient and covers all necessary details without excessive verbosity. Could be split into shorter sentences for readability, but it earns its place.

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 (one optional param, no output schema), the description is complete: it covers usage scenarios, token handling, and setup. The context signals support that the description fully compensates for the lack of schema documentation.

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 the description thoroughly explains the only parameter: 'token' is a JWT, and passing it authenticates, while no args yields a link. This adds critical meaning beyond the schema's bare type declaration.

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 authenticate for IDE agents via browser login and token retrieval. It specifies the action (log in, copy access token) and the resource (this server's config or session). It distinguishes itself from siblings by focusing on authentication, though it doesn't explicitly differentiate from '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 explicit usage instructions: it explains the two modes (permanent config header vs. session-only token) and when to use each. It also states how to call the tool (with token or without args). However, it doesn't explicitly mention alternative tools or exclusions, so it's not a perfect 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds behavior details: when all providers are connected it returns authenticated:true and empty pending[], and when credentials are missing it returns connect_url and per-install URLs. This gives useful conditional response context not 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-loaded with the core action and supporting details. Every sentence earns its place without 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?

The description covers the main scenarios (all connected, missing credentials) and indicates the return fields. It doesn't address a partial-connection state, but for a simple status tool with good annotations and no output schema, it is sufficiently 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 the schema is fully covered by default. The description adds no parameter-specific details because there are none; the baseline 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 uses a specific verb ('Returns') and resource ('connection status and URLs'), clearly distinguishing it from sibling tools like 'authenticate' by focusing on status retrieval. It also describes the two main operational states, making the purpose unambiguous.

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 tool reports connection state and URLs, implying its use for checking connectivity. It does not explicitly name alternatives or exclusions, but the context is sufficient to guide appropriate usage.

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 the annotations (readOnlyHint=false, etc.), the description discloses many behavioral details: invoke works even if MCP is not installed, returns connect/auth links or checkout links when needed, and writes require workspace owner/admin. It also explains the flag for installed_in_toolkit vs installed_in_workspace. 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?

While lengthy, the description is well-structured with 'Core flow', 'KEY', and 'PROMPT LIBRARY' sections, and every sentence adds value. It is front-loaded with the most critical information but could be more concise given the 23 parameters and multiple features.

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, multiple actions, and no output schema, the description covers all major aspects: the core flow, edge cases (connect/checkout links), permission requirements, and the separate prompt library functionality. It is sufficiently complete for an agent to select and invoke the appropriate action.

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%, so the description must compensate. It explains the purpose of key parameters (query, action, mcp_id, tool_id, arguments) through the flow, and mentions prompt_vars in the get_prompt context. However, not all 23 parameters are explicitly defined (e.g., immediate, tier_slug, report_context), though the multi-action design implies contextual 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 is the official mcp.ai marketplace, a catalog of every MCP/tool and the way to run them. It enumerates all supported actions (search, describe, install, invoke, etc.) and distinguishes the core flow from the prompt library. This is specific and unambiguous.

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 explicit guidance: prefer invoke for single/occasional use, use install to make an MCP permanent, and distinguishes between the marketplace and prompt library actions. It also mentions that writes require owner/admin permissions, which informs when to use 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 and idempotentHint, so the description adds little on safety. It does disclose the cost model ('pague por consulta') and LGPD responsibility, but it does not mention response format, pagination, or error 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 three sentences long and begins with the core purpose, followed by payment and compliance details. It is concise and readable, though the legal sentence occupies space that could have clarified parameters.

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 and no output schema, the description is incomplete. It explains the tool's high-level purpose and some context, but not how to invoke it correctly or what the parameters mean, making it insufficient for a complex 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?

The schema has 8 parameters with 0% description coverage, and the description does not explain any of them (e.g., 'pagina', 'data_inicial', 'login_cpf'). This leaves the agent guessing about parameter meaning, and the description fails to compensate.

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 is a 'consulta' (query) for 'Notas Emitidas' (issued NFS-e) from 'Receita Federal', a specific verb and resource. It distinguishes itself from sibling tools, which are unrelated (authenticate, connect, etc.).

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 ('pague por consulta com crédito pré-pago') and no platform credentials ('sem credenciais da plataforma'), but it does not explicitly state when to use this tool over alternatives or provide exclusion criteria. Sibling tools are unrelated, so no direct alternative is addressed.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds minimal behavioral context beyond stating that the conversation array is needed for reproduction. It does not disclose any side effects, storage implications, or error behavior, but it also does not contradict 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, compact sentence paired with a brief instruction. It communicates the core function in two short sentences with no fluff 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 tool with 3 parameters, zero schema descriptions, and no output schema, the description is notably incomplete. It fails to define 'message' and 'context', does not describe the expected return or side effects, and the conversation parameter is only partially described. Agents would likely need to guess or probe the tool to use 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?

Schema description coverage is 0%, so the description must explain all parameters. It only mentions the 'conversation' parameter, and even then calls it an 'array' while the schema type is string (a potential mismatch). The required 'message' parameter and the optional 'context' are not explained at all, leaving agents without guidance on how to fill them.

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.' It uses a specific verb (report) and identifies the resource (bug/feature/feedback). No sibling tool serves a similar purpose, so differentiation is not needed, but there is no explicit mention of 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 implies when to use the tool by mentioning 'Include the conversation array with recent messages for reproduction,' which suggests it's appropriate when a reproduction context is available. However, it does not specify when not to use it, nor does it reference any alternative feedback channels.

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 fully declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the specific scope ('platform and adapter versions'), which clarifies exactly what version information is returned. Minor deduction because it doesn't mention if there's any network call or if it's purely local, but that's largely immaterial for this kind of 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?

A single sentence, no fluff, every word earns its place. Ideal length for an informational endpoint.

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 simple, has no parameters, no output schema needed, and the description covers the purpose and return scope. The sibling tools are distinct (connect, authenticate, etc.), so there's no confusion. Nothing 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?

There are zero parameters, and schema description coverage is 100% (vacuously). Per the rubric, 0 parameters = baseline 4, and the description adds value by clarifying the meaning of the return value ('MCP platform and adapter versions'), covering the version output details. This justifies a 5.

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 ('Show') and resource ('current MCP platform and adapter versions'), making the tool's purpose immediately clear. It distinguishes itself from siblings by being a simple informational endpoint, and there's no ambiguity about what it returns.

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 clearly implies when to use this tool (whenever you need version information), but it doesn't explicitly mention alternatives or when not to use it. Given the trivial nature and the presence of sibling tools like toolkit_info and report_bug, a small note about when to prefer this over toolkit_info could push it to 5, but the context makes it evident.

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, destructiveHint=false, so the safety profile is fully covered. The description adds the specific content of the return (installed MCPs, status, accounts, counts) which is useful, but doesn't add behavioral details like whether it makes network calls or how fresh the data is. With annotations covering safety, a 3 is appropriate.

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 purpose ('Returns the current toolkit state') and then enumerates the specific data points. Zero waste, perfectly concise.

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 tool with strong annotations, the description is complete. It tells the agent exactly what information will be returned. It could mention whether the data is real-time or cached, but that's a minor gap given the tool's 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, so the description doesn't need to explain parameter semantics. The baseline for 0 params is 4, and the description correctly focuses on what the tool returns rather than 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 returns toolkit state, listing specific elements: installed MCPs, connection status, connected accounts, and catalog tool counts. This is specific and distinguishes it from siblings like show_version (version info) and authenticate (auth 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 this is a diagnostic/status tool, useful for checking connections and accounts before using other tools. It doesn't explicitly state when not to use it or name alternatives, but the context of sibling tools (authenticate, connect) makes the usage context clear.

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