SEFAZ: Cadastro Centralizado de Contribuinte (CCC)

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

The description discloses that the token can be stored permanently in config (non-expiring) or used for a session, and that calling without args returns a login link. This goes beyond the annotations, which only indicate idempotency and non-destructiveness.

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 packs a lot of information. It's front-loaded with the purpose, then gives actionable steps. While slightly dense, it remains clear and not verbose.

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 authentication tool with one optional parameter, the description covers the main workflow and both token storage options. It mentions the login link but doesn't detail the response format; however, given the simplicity, it's 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 schema has only a 'token' string with no description. The description explains that token is a JWT to paste for session-only login, and that it can be omitted to retrieve the login link, fully compensating for the lack of schema documentation.

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 for authentication, describing the browser login flow and token retrieval. It distinguishes between permanent and session-only login modes, making its 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?

It provides explicit instructions for two use cases: configuring a permanent token via header vs session-only token passed as parameter, and also explains the no-args call to get the link. This gives clear guidance on when to use each invocation.

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. The description adds useful behavioral details about the return values in different states (authenticated:true with empty pending[], or connect_url and per-install URLs), going beyond what annotations provide.

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 purpose, and each sentence adds meaningful information about the tool's behavior. 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?

For a simple status-check tool with no parameters and no output schema, the description provides sufficient context about what it returns in both possible states. It doesn't discuss when to use it versus siblings, but that's covered under usage guidelines. The description is adequate for an agent to invoke 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?

The tool has zero parameters, so schema coverage is trivially 100%. The description doesn't need to explain parameters; the baseline for 0 params is 4. The description focuses on output behavior, which 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 connection status and URLs, with specific details about two output states (all connected vs. missing credentials). This distinguishes it from siblings like authenticate, though it doesn't explicitly name 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?

No guidance is given on when to use this tool versus alternatives. While it implies it's for checking status, it doesn't mention that authenticate is for initiating connection or that other tools might be more appropriate in certain contexts.

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?

With annotations only providing openWorldHint=true, the description carries the full burden and excels: it discloses that invoke runs tools even when not installed, that it does not bloat the toolkit, that credential needs produce a connect link, that empty-wallet paid tools return a checkout link requiring retry, that install/uninstall/subscribe/cancel require workspace owner/admin, and that writes include the one-off install behind invoke. This is rich, non-obvious behavioral context far 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?

The description is a dense single paragraph with no line breaks or headers. Every sentence earns its place, but the sheer length and run-on structure make it harder to parse. For a 23-parameter dispatcher covering 14 actions, the density is justified, but structured formatting (bullets or action groupings) would have improved scannability.

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 enormous complexity (14 actions, 23 params, no output schema, only openWorldHint annotation), the description is remarkably complete: it covers the search/describe/invoke flow, install vs invoke semantics, auth and payment edge cases, permission requirements, the prompt library subdomain, and the last-resort request_mcp path. The only minor gap is that some parameter values (e.g., immediate, tier_slug) are not individually explained, but the action-level coverage is sufficient for an agent to select and invoke the tool 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 compensate for 23 undocumented parameters. It does so by explaining the action enum values and the roles of key parameters (mcp_id, tool_id, arguments, prompt_slug, prompt_vars) through the described flows. However, several parameters (tier_slug, cancel_reason, immediate, conversation, prompt_targets, report_context) are not explicitly mapped to their actions, leaving some ambiguity despite the strong overall context.

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 marketplace as the official mcp.ai catalog and execution layer, with specific verbs for each action ('search discovers', 'describe returns', 'invoke RUNS'). It distinguishes this dispatcher tool from siblings by covering the full lifecycle of discovering, evaluating, invoking, and installing MCPs, and it explicitly covers the prompt-library subdomain. The scope is unambiguous and richly specified.

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: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT in the active toolkit'. It also explains the core flow (search → describe → invoke), when install is appropriate, and that report_bug/request_mcp are for feedback and new-build requests. It even names the alternative for listing currently callable tools (list_tools). This is exemplary usage 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 idempotentHint true, destructiveHint false, and readOnlyHint false, so the safety profile is known. The description adds that the conversation array is expected for reproduction, which is useful. However, it does not disclose other behaviors like whether authentication is required (sibling authenticate suggests it might be) or what happens after submission. With annotations present, the bar is lower, so this is acceptable but not rich.

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 purpose, and each sentence earns its place. No fluff or redundancy. It is appropriately concise for the tool's complexity.

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 3 params and no output schema, so the description need not be extensive. However, it lacks sufficient guidance on parameter usage (especially message and context) and does not describe what happens after reporting. The conversation array hint is helpful, but overall the description is adequate but not 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%. The description mentions the conversation array but does not clarify the meaning or format of the message (required) or context parameters. It partially compensates by instructing to include the conversation array, but the primary 'message' field is not explicitly tied to the bug description, and 'context' is unexplained. The description adds minimal semantic value beyond the 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: 'Report a bug, missing feature, or send feedback.' This is a specific verb (report) with resource types, distinguishing it from sibling tools like authenticate, connect, or show_version, which serve 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?

The description implies usage for reporting issues or feedback but does not explicitly discuss when to use or not use this tool, nor does it name alternatives. The instruction to include the conversation array gives a practical tip, but there is no explicit guidance on scenarios where this tool should be avoided.

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 valuable context: hosting on the platform without platform credentials, per-query cost with prepaid credit, the public nature of data, and LGPD responsibilities for the client. It does not contradict annotations and enriches behavioral understanding.

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 core purpose (SEFAZ: CCC query from official source) before adding practical and legal details. Every clause adds value, with no redundancy or unnecessary 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?

Given the tool has 8 parameters and no output schema, the description is insufficient. It does not explain parameter formats, valid values, or how to structure queries. The high-level business context is present, but essential technical details are missing, leaving the agent uncertain about how to properly invoke the 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%, and the description offers no information about any of the 8 parameters (e.g., ie, cpf, cnpj, login_cpf, etc.). It only mentions a query without clarifying which parameters are needed beyond the required 'uf'. The description fails to compensate for the schema's lack of documentation.

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 a query for the Centralized Taxpayer Registry (CCC) from SEFAZ, specifying a particular resource and action. It distinguishes itself from sibling tools by naming the specific official source and nature of the data, though siblings are largely unrelated.

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 and data legitimacy but does not explicitly state when to use this tool versus alternatives or what conditions apply. It implies the tool is for accessing public official data but lacks explicit 'when not to use' 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 clearly indicate readOnlyHint: true, idempotentHint: true, and destructiveHint: false, which align with the non-mutating nature of showing versions. The description uses 'Show' which consistently implies a read-only operation with no side effects.

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 and to the point, using a single clear sentence. The schema is minimal and properly structured with an empty properties object, which is appropriate for a parameterless 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?

The description covers the main purpose, and annotations provide behavior context)Skip_significant gaps. However, there is no output schema, so the exact structure of the version information is not specified, which is a minor omission for such a straightforward 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 input schema has zero parameters and the property list is empty, which matches the tool's purpose. Since there are no parameters, there is no ambiguity about what inputs are expected.

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 'Show the current MCP platform and adapter versions' unambiguously states what the tool does. It clearly indicates that it retrieves version information for both the MCP platform and adapters.

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 tool is self-explanatory and requires no parameters or prerequisites. However, there is no explicit guidance on when to invoke it relative to other sibling tools like 'authenticate' or 'connect', though its simplicity makes it obvious for version queries.

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=true, destructiveHint=false, and idempotentHint=true, so the description doesn't need to re-state safety. It adds useful context beyond annotations by detailing exactly what information is returned (installed MCPs, connection status, accounts, catalog tool counts), thereby enhancing behavioral transparency for a read operation. 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 the key data points. Every word contributes to clarity, with no filler 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?

Given that the tool has no parameters, no output schema, and strong annotations that indicate a safe read operation, the description is complete. It clearly enumerates the return contents, which is all that's needed for the agent to select and use the tool accurately.

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 0 parameters, and schema coverage is 100% (vacuously). Since there are no parameters to describe, the description's job is not to add parameter semantics but to clarify what the tool returns, which it does. As a result, the baseline for 'no params' is 4, and the description meets that.

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: it returns the current toolkit state, listing installed MCPs, connection status, accounts, and catalog tool counts. It uses specific nouns (toolkit state, installed MCPs) and a clear verb ('retrieves' implied by 'Returns'), but it doesn't explicitly differentiate from sister tools like '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 provides context on when to use it ('current toolkit state') but doesn't mention alternatives or when not to use it. It doesn't explicitly contrast with siblings like 'show_version' or 'authenticate', so it leaves the choice ambiguous to some extent.

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