SEFAZ PI Visualizar certidões CNDA: CND

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

With annotations only supplying idempotentHint=true and readOnlyHint=false, the description adds meaningful behavioral context: the permanent vs. session-only distinction, how to call with/without args, and the non-expiring nature of the header-based connection. Doesn't mention error or failure behavior, which would round it out.

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 dense three-sentence description where every clause earns its place: audience, recommended approach, fallback approach, and invocation semantics. It's a bit run-on and mixes setup guidance with call signatures, but it's front-loaded and contains zero fluff.

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 single optional-param tool with no output schema, the description covers both invocation modes and their persistence trade-offs thoroughly. An agent could drive the full flow without consulting external docs. It doesn't cover response shapes or error cases, but nothing here is incomplete enough to drop below a 4.

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% and the token param has no description, so the description carries the full weight — and it does so well by explaining the token is a JWT pasted by the user and that calling with no args yields the login link. Slightly more detail on the JWT's origin or validation could push this to 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 clearly conveys the verb+resource ('log in in the browser, copy the access token') and names the target audience (MCP.AI for IDE agents like Cursor). It's unambiguous about what the tool does, though it doesn't explicitly differentiate itself from a sibling like `connect` — a 5 would require that explicit sibling distinction.

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?

Provides explicit guidance on when to use what: the 'Best' permanent approach (server config header) vs. session-only login via the token argument. This effectively scopes the tool's two usage modes, though it doesn't cover when NOT to use the tool or name 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, which align with a safe status query. The description adds useful behavioral context: the exact meaning of authenticated:true and the presence of pending[], plus the per-install URLs. No contradiction found.

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 concise sentences that front-load the core purpose, then explain the two key states. Every word earns its place, with no filler or redundant restatement.

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 status tool with clear annotations and a description that covers the two possible outcomes, the description is complete. It also gives enough context to distinguish from authentication and connection setup actions. No output schema, but the description covers the returned fields adequately.

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% (vacuously). The description provides rich semantic detail about the output and conditions, which is the relevant 'parameter' here. With no params, the baseline is high, and the description exceeds expectations by explaining the response semantics.

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 conditions for when authenticated:true and empty pending[] are returned, and when connect_url is provided. It distinguishes this from siblings like authenticate and show_version by focusing on status/reporting rather than action or version 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 when to use this tool: to check connection status and obtain URLs for setup. It provides clear context on what the output means (authenticated vs. missing credentials) but does not explicitly state when not to use it or mention alternatives. However, given the simple status-query nature, this is acceptable.

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?

Even with annotations, the description adds meaningful behavioral context: invoke runs MCPs even when not installed, does not bloat the tool list, may return connect or checkout links, and install makes tools permanently available. Permission and login requirements are disclosed accurately, and nothing contradicts 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 long, but it is front-loaded, procedural, and dense with useful information rather than filler. The core flow, distinctions between invoke/install, payment/credential behavior, permissions, and the prompt-library subsection are logically organized, though heavier structure or bullets would make the 23-parameter surface easier to scan.

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 a complex dispatcher-style tool, no output schema, and no parameter descriptions, the description covers the primary flows, auth/payment outcomes, permission constraints, and the prompt library surprisingly well. Minor gaps remain, such as resume, immediate, tier_slug, and detailed cancellation/report parameter behavior, but the overall tool context is complete enough for an agent to act effectively.

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 23 parameters with 0% description coverage, so the tool description carries the responsibility, and it does much of that work: action values, mcp_id, tool_id, arguments, query, and prompt fields are given real semantics through the core flow and prompt-library explanation. Some parameters remain opaque (e.g., immediate, tier_slug, cancel_reason, prompt_targets), which keeps this from a 5, but the description compensates well for the bare 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 defines the marketplace as the central MCP catalog and execution surface, with explicit verbs for each capability: search, describe, install, uninstall, subscribe, cancel, list_tools, request_mcp, and the prompt-library actions. It distinguishes the marketplace from sibling tools by making its resource (catalog + runner + prompt library) concrete and by outlining a core flow rather than just restating the name.

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?

Provides exceptionally explicit usage guidance: prefer invoke for one-off use, use install only for permanent toolkit membership, use request_mcp when nothing fits, and use list_tools to see what is callable now. It also notes that write actions require workspace owner/admin privileges and that credential/payment failures map to connect/checkout links before retrying.

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 establish non-read-only, idempotent, and non-destructive behavior. The description adds context about including the conversation array for reproduction, which is a behavioral nuance. It does not disclose side effects like where the bug report goes, but with annotations covering safety, this is adequate.

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 only two sentences, front-loaded with the purpose and then a key usage note. Every word contributes to understanding, 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?

For a simple bug-report tool with no output schema, the description covers the core action and highlights the most important parameter. It lacks any mention of return values or post-call behavior, but given the tool's low complexity, this is a minor gap. Overall, it is sufficient for an agent to invoke 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 coverage is 0%, so the description must compensate. It explains the 'conversation' parameter's purpose ('recent messages for reproduction') but does not clarify 'context' or 'message' beyond what their names imply. This gives partial parameter guidance but not full coverage of all three 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 states 'Report a bug, missing feature, or send feedback,' providing a specific verb and resource that distinguishes it from sibling tools like authenticate and connect. The purpose is unambiguous and immediately understandable.

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 indicates when to use the tool ('Report a bug, missing feature, or send feedback') and provides a concrete instruction ('Include the conversation array with recent messages for reproduction'). However, it does not explicitly mention alternatives or exclusions, though siblings are unrelated so no conflict is expected.

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 and idempotentHint, but the description adds valuable behavioral context: no platform credentials are needed, payment per query is required, data is public (not confidential), and the client is the data controller under LGPD. These details go beyond annotations and clarify operational constraints 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 concise paragraph that front-loads the core purpose in the first sentence. It then adds payment and data nature details. While the LGPD disclaimer and repeated emphasis on data being public add some redundancy, the overall structure is efficient and each sentence contributes useful context.

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 absence of an output schema and 0% parameter descriptions, the description should provide complete guidance on query construction. It covers payment and data nature but omits critical instructions: whether cpf or cnpj is mandatory, how to specify the certificate type, and what the response will contain. This leaves a significant gap for an agent to use 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?

The schema has 0% description coverage, leaving the description responsible for clarifying parameters. However, it only vaguely references 'certidões CNDA' and does not explain the meaning or usage of 'tipo_certidao', 'cpf', or 'cnpj' beyond their names. It fails to compensate for the schema's lack of descriptions, offering no guidance on which identifiers are required or their formats.

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: 'SEFAZ PI Visualizar certidões CNDA: CND, consulta em fonte oficial.' It names the specific action (visualizar/consultar) and resource (certidões CNDA). This distinguishes it from sibling tools (authenticate, connect, marketplace, etc.) which operate on platform-level concerns, 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?

The description provides clear context on usage: the tool is hosted by the platform, requires no platform credentials, and charges per consultation with prepaid credit. It implies usage for querying official Brazilian tax certificates. However, it does not explicitly state when to use this tool over alternatives or mention any exclusions; because siblings are unrelated, this absence is minor but prevents a perfect score.

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 well-covered. The description adds minimal behavioral context beyond that; it doesn't describe output format or that it might require an active connection, but the annotations carry most of the burden.

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 says exactly what the tool does with no filler. It is appropriately front-loaded and every word adds value.

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, zero-parameter, read-only tool, the description is complete. It doesn't need to explain return values since no output schema existsholed, but it could mention what the output looks like. However, given the tool's simplicity, the information 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 no parameters, and the schema covers 100% (empty). The description does not need to explain parameters. Since there are no parameters, the baseline is 4, and the description doesn't detract from 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 purpose: to show current MCP platform and adapter versions. It uses a specific verb ('show') and names the resources (MCP platform and adapter versions). While it doesn't explicitly distinguish from siblings, the purpose is unambiguous and not a tautology.

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 it (when you need version information) but does not provide explicit guidance on when not to use it or alternatives. With no parameters and a clear purpose, it's adequate but lacks explicit 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so no contradiction. The description goes beyond annotations by detailing the specific return contents (installed MCPs, connection status, accounts, tool counts), which helps the agent understand what to expect. It does not discuss potential latency or side effects, but none are indicated for a read-only state query.

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, information-dense sentence that front-loads the action ('Returns') and concisely enumerates the output components. Every word earns its place, with 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 read-only tool with no parameters and no output schema, the description fully covers what the tool does and what it returns. It is complete and self-sufficient, leaving no significant gaps for the agent to infer.

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 the schema shows an empty properties object. With 0 parameters, the baseline is 4, and the description correctly focuses on the output rather than inputs. No additional parameter semantics are needed.

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 the specific verb 'Returns' and identifies the resource as 'current toolkit state', listing concrete elements (installed MCPs, connection status, accounts, catalog tool counts). This clearly distinguishes the tool from siblings like authenticate or show_version, which serve different purposes.

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 by stating exactly what information the tool returns, implicitly indicating it should be used when an overview of the toolkit's connections and tool counts is needed. It does not explicitly mention alternatives or when not to use it, but the uniqueness of the tool among siblings makes this omission minor.

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