SEFAZ SC: NFE

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

The description discloses the authentication process, including the token acquisition and its two application methods. It does not contradict the annotations (idempotentHint=true, destructiveHint=false). While it does not detail side effects or potential issues, the description adds useful behavioral context beyond the bare 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 concise, fitting the two main usage scenarios into a single sentence. It is not verbose and conveys all necessary information without redundant phrasing.

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 all relevant aspects: how to obtain the token, two ways to using it (permanent vs. session), and the behavior when no arguments are provided. It does not describe the return value, but that is not essential given the tool's straightforward 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?

The only parameter 'token' is explained in context: it is the JWT token to be used for session-only login. The description clarifies that the token is optional (since calling with no args retrieves the link), which supplements the sparse 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 the tool's purpose: to authenticate by logging in and obtaining a token, and it distinguishes between permanent (via config) and session (via token argument) authentication methods. It is unambiguous and specific.

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 explicitly explains when and how to use the tool: it provides two usage patterns (adding the token to config for permanent access, or passing the token for session-only access), and notes that calling with no arguments returns the login link. This gives clear guidance on when to use each approach.

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, so the safety profile is covered. The description adds concrete behavioral detail about response states, such as authenticated:true with empty pending[] and connect_url when credentials are missing.

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 primary purpose and then specific conditional outcomes. Every phrase contributes useful information with no waste.

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 status tool, the description fully captures the return values and conditional behavior. Although there is no output schema, the description effectively substitutes it by explaining the two distinct response scenarios.

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 trivially 100%, so the description has no parameter burden. The baseline of 4 is appropriate given there is nothing to explain.

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, using a specific verb and resource. It distinguishes itself from sibling tools like authenticate and show_version by emphasizing status retrieval rather than an action.

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 conditional contexts ('When all providers are connected', 'When credentials are missing') that imply when to use the tool and what to expect. It does not explicitly exclude alternatives, but the sibling names make the distinction clear.

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?

Despite having annotations (readOnlyHint=false, idempotentHint=false), the description adds substantial behavioral context: invoke runs tools one-off without installing or bloating the toolkit, credentials trigger a connect link, paid/empty wallet triggers a checkout/top-up link then a retry, writes require workspace owner/admin, and search/describe flags installed_in_toolkit vs installed_in_workspace. None of these details are in the annotations, and the description is consistent with them (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?

For a 23-parameter multi-action tool this is a dense, information-rich description where nearly every sentence earns its place. It front-loads the core identity and flow, then key caveats (one-off invoke, credential/payment links), then secondary acts (install, list, billing, request, prompt library). The main weakness is structure: it's a single unbroken paragraph with no grouping or bullet lists, which could be more scanable for an agent.

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 (23 parameters, 0 required, no output schema, no per-parameter descriptions), the description covers the two major operating areas extremely well — the MCP discovery/run/install flows (with auth and payment edge cases) and the prompt library flow (including login-free share links). It also addresses the permission model and workspace/toolkit distinctions. Minor gaps remain: the resume action semantics and the precise return shapes of search/list results are not spelled out, but overall it is close to 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?

Schema description coverage is 0%, but the description compensates for the central action parameter by explaining what each action does (search=discover by intent, describe=full profile with id+params+pricing+auth, invoke=runs that tool) and by describing the prompt library flow (search_prompts, get_prompt, publish_prompt) and the cancel context (billing). However, some parameters (limit, params, immediate, conversation) and the 'resume' action in the enum are left unexplained, and the description references actions (invoke, request_mcp, list_tools) that are not present in the action enum — so coverage is strong but not complete.

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 a concrete resource and action set: 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It uses specific verb-action pairs ('action=search discovers', 'describe returns one MCP's full profile', 'invoke RUNS that tool') and explicitly differentiates itself from siblings like authenticate, connect, and toolkit_info. It also distinguishes its own sub-modes (search vs install vs invoke vs prompt-library functions), so there's no ambiguity about what 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 gives explicit decision rules: 'Use install only to make an MCP PERMANENT in the active toolkit' vs 'prefer invoke for a single/occasional use'; 'list_tools lists what is callable right now'; subscribe/cancel 'handle per-MCP billing'; request_mcp for when 'nothing fits'. It also provides exclusion guidance (invoke returns a connect link when credentials are needed; a checkout link when the wallet is empty) and permission prerequisites (writes require owner/admin).

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 provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds minimal behavioral context by instructing to include conversation for reproduction, but does not disclose side effects, permissions, or post-submit 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 concise sentences: the first states the purpose; the second gives a parameter-focused instruction. No unnecessary words or repetition.

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 with no output schema, and the description covers purpose and conversation guidance. However, it omits any mention of return value, prerequisites like authentication, or what happens after reporting, which is relevant given the sibling 'authenticate' and 'connect' tools.

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 description mentions only the 'conversation' parameter ('Include the conversation array'), leaving the required 'message' and optional 'context' undocumented. Given 0% schema coverage, the description should compensate more for these parameters, but it only clarifies one of three.

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 reports a bug, missing feature, or feedback using the verb 'report' and a specific resource. This clearly distinguishes it from sibling tools like authenticate or show_version.

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 tells when to use the tool (report a bug/feedback) and provides a specific usage instruction (include conversation array). It does not explicitly mention exclusions or alternatives, but the siblings are unrelated, making alternatives unnecessary.

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 readOnly, idempotent, and non-destructive, so the description adds valuable context: hosted on the platform, no platform credentials, pay-per-query with prepaid credits, and the data is public (not confidential). It also clarifies the client's data controller responsibility under LGPD, going beyond the raw 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 concise, with a clear first clause stating the purpose, and subsequent clauses adding necessary context about cost, data source, and legal responsibilities. It avoids redundancy and is appropriately front-loaded, though the legal phrasing could be trimmed slightly.

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 one-parameter lookup, the description covers the data source, cost model, and safety profile sufficiently. However, it does not explain the return format or any input constraints (e.g., required length or formatting of the NFE identifier), which would be helpful given the lack of an output schema. It's adequate 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 schema defines only one parameter 'nfe' as a string, but the description provides zero explanation of its format or meaning beyond the tool name. With 0% schema description coverage, the description should compensate, but it only says 'NFE' without specifying the expected identifier format (e.g., access key, number, length). This leaves ambiguity for the agent.

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 action (consultar/consult) on the resource (NFE from SEFAZ SC) and distinguishes it from the generic siblings like authenticate or show_version. It specifies it queries official Brazilian sources, setting it apart from typical CRUD 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 implies usage for retrieving official NFE data but does not explicitly state when to use it or when not to. It mentions the paid nature and LGPD compliance but lacks direct alternatives or exclusions. The context is sufficient for a simple lookup but not for decision-making among multiple tools.

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 matches the read-only, idempotent, non-destructive annotations and adds clarity that it reports both platform and adapter versions. However, it does not provide additional behavioral context such as output format, whether authentication is required, or whether network access is involved.

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, front-loaded sentence with no filler or redundancy. It communicates the essential purpose efficiently.

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 version lookup with strong annotations, the description is largely complete. It could additionally state what the output contains or that the operation is local, but given the tool's simplicity, the current text is sufficient.

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 the input schema is empty, so there is no parameter meaning to explain. The description does not need to compensate for missing parameter details, and the non-applicability of parameters is clear.

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 identifies the exact resource ('current MCP platform and adapter versions'). It is distinct enough from sibling tools like toolkit_info because it specifically focuses on version information.

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 no guidance on when to use this tool versus alternatives, no mention of prerequisites, and no exclusions. While usage is somewhat obvious for a version tool, the description does not explicitly address choosing between available sibling tools.

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 clear. The description adds value by detailing exactly what data is returned (installed MCPs, statuses, accounts, catalog tool counts), which is behavioral context beyond the annotations. No contradictions or missing side effects for a read-only 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 a single, well-structured sentence that front-loads the purpose ('Returns the current toolkit state') and then enumerates the specific data included. Every word earns its place with zero fluff, making it highly efficient and memorable.

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 state query with no output schema, the description is complete. It exhaustively enumerates what the returned state includes (installed MCPs, connection status, connected accounts, catalog tool counts), leaving no ambiguity about the tool's output. Annotations cover side-effect safety, and the description covers the data payload.

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 per the rubric baseline is 4. The description does not need to explain parameter semantics since there are none. Schema coverage is trivially 100%, and no additional parameter documentation is 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 the tool returns the current toolkit state, listing specific components: installed MCPs, connection status, accounts, and catalog tool counts. This is a specific verb+resource that distinguishes it from sibling tools like connect or authenticate, which perform actions rather than report status.

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 a clear context: it is a state-query tool for inspecting toolkit health and configuration. It doesn't explicitly name alternatives or exclusions, but given the sibling tool names (authenticate, connect, marketplace), the intended use is implied and unambiguous. Lacks explicit when-not-to-use guidance but is otherwise clear.

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