Prefeitura SC Itajaí: Certidão Negativa de Débitos

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

The description adds behavioral context beyond annotations: it explains the difference between permanent (config header) and session-only (token passed) connections, and states that calling with no args returns a link. This is valuable information not provided by the annotations (which only indicate idempotence 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 a bit verbose but every sentence adds value. It front-loads the core purpose ('log in in the browser, copy the access token') then details two alternatives. It could be tightened but is well-structured and not redundant.

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 authentication tool with no output schema, the description covers all necessary aspects: purpose, two usage modes, and token handling. It is complete enough for an agent to invoke correctly without additional context.

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 has a single optional token property with 0% description coverage. The description fully explains the token's format (JWT), when to pass it (after user pastes), and the alternative of calling without args to get a link. This compensates completely 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 it is for authentication ('log in in the browser, copy the access token') and distinguishes between permanent and session-based login. It uses specific verbs like 'log in' and 'copy' and describes the resource (access token). It is clearly distinct from siblings like 'connect' or '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?

Provides explicit usage instructions: either add the token to config for permanent access or paste it for session login. Explains when to call with a token and when to call with no args. While it doesn't name alternative tools, it clearly explains the two modes and prerequisites (browser login, token copy).

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 substantial behavioral detail beyond the annotations: it explains response conditions (authenticated:true and empty pending[] when all connected; connect_url and per-install URLs when credentials missing). This is useful context not present in the schema or 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, directly states the tool's function, and provides conditional details without unnecessary fluff. Every sentence 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 status-check tool with no parameters and no output schema, the description is complete. It covers the main success case and the edge case of missing credentials, both with clear response details.

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 empty and the description does not need to explain parameters. Per the rubric, 0 params earns a baseline of 4. The description instead 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, specifying two distinct outcomes based on credential presence. This distinguishes it from sibling tools like authenticate, which likely performs authentication, and other unrelated 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 provides clear context for when to use the tool (to check connection status and obtain URLs) but does not explicitly mention when not to use it or name alternative tools. The sibling `authenticate` is implied as a related but different action.

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 though annotations are sparse, the description richly discloses behavior: invoke runs one-off without installing or bloating the toolkit, writes require workspace owner/admin, missing credentials return a connect link, and empty wallet returns a checkout/top-up link. It also explains the prompt-library side of the tool and the installed_in_toolkit vs installed_in_workspace flags.

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 but appropriately front-loaded with the tool's identity and core flow before expanding into per-action details. It is a single long paragraph rather than scannable structure, but every sentence adds meaningful content for a tool with 14 distinct actions, so the length is justified.

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 complex multi-action hub with no output schema and minimal annotations, the description is unusually complete: it covers core flows, permissions, failure modes, and prompt-library behavior. However, the absence of output-shape details and the under-documented optional parameters leave some practical gaps for an agent trying to call every action 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?

With 0% schema description coverage across 23 parameters, the description must carry a heavy burden. It explains the key action enum values and core flow concepts like tool_id, arguments, and prompt variables, but many parameters remain undefined: limit, query, immediate, tier_slug, conversation, cancel_reason, prompt_targets, and others. The description covers the central workflow well but leaves numerous optional parameters ambiguous.

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 the official mcp.ai marketplace catalog and execution hub, with explicit supported intents like 'find an MCP that does X' and 'is there a tool for Y'. It enumerates the core search → describe → invoke flow and distinguishes itself from siblings by covering catalog discovery, one-off execution, installation, billing, and prompt-library access.

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', 'Use install only to make an MCP PERMANENT', and 'request_mcp asks us to build a NEW MCP when nothing fits'. It also clarifies when invoke returns a connect or checkout link and that retry is expected after the user completes the action.

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 readOnly/idempotent annotations, the description discloses important operational traits: no platform credentials are needed, each query is paid via prepaid credit, the data is non-confidential and publicly available to citizens, and LGPD controller responsibilities apply. This gives the agent essential context about cost, auth, and data sensitivity.

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 reasonably compact and front-loaded with the core purpose; the subsequent sentences about hosting, payment, and LGPD add useful context. It is slightly more verbose than strictly necessary but not padded.

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 business context, source legitimacy, payment, and privacy obligations, which is good for tool selection. However, it omits how to use the cpf/cnpj parameters and what the returned certificate contains, and with no output schema this leaves meaningful gaps for successful invocation.

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 schema description coverage at 0%, the description had to explain cpf/cnpj, but it never mentions either parameter or their roles. The schema only provides string types with no descriptions, and the description does not compensate, leaving the agent to guess how to populate the two optional identifiers.

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 specifies a concrete action and resource: 'consulta em fonte oficial' of the 'Certidão Negativa de Débitos' from Prefeitura SC Itajaí. This clearly distinguishes the tool from siblings such as authenticate, marketplace, and report_bug.

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 clear context for use: the query comes from an official Brazilian source, requires no platform credentials, and consumes prepaid credit. It does not explicitly name alternatives or state when not to use the tool, but the domain context is sufficient given the unrelated sibling set.

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 the tool is idempotent and non-destructive. The description adds the helpful context that conversation data is needed for reproduction, but does not disclose what happens after submission (e.g., ticket creation, response). This is adequate given annotation coverage, but not richly detailed.

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 purpose, and no filler. Every word contributes meaning, making it highly efficient.

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, and the description covers the core purpose and the one especially important parameter (conversation). However, it omits the required nature of 'message', fails to mention 'context', and provides no information about return values or post-submission behavior. It is 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?

Schema description coverage is 0%, so the description must compensate. It explains the 'conversation' parameter's role (reproduction) but ignores 'context' and does not clarify that 'conversation' is a JSON string despite being called an array. The required 'message' parameter is only implicitly tied to 'report a bug/feedback'. This is insufficient for a 3-parameter tool.

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 report a bug, missing feature, or send feedback. This is a specific verb plus resource, and it differentiates from sibling tools (authenticate, marketplace, etc.) which serve unrelated 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 when to use this tool: whenever a user encounters a bug, missing feature, or wants to provide feedback. It also instructs to include recent conversation messages for reproduction. However, it does not explicitly mention alternatives or when not to use it, though no direct alternative exists among siblings.

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 description doesn't need to repeat safety. It adds the value of specifying exactly what versions are shown, which is useful beyond the schema that has no properties.

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?

Single clear sentence conveying the purpose without any fluff. Perfectly appropriate size.

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 (no params, no annotations beyond safety hints, no output schema), the description is sufficient. It tells the agent exactly what the tool provides, though it could theoretically mention the format or granularity of versions (e.g., individual components) but that's not critical.

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 there is nothing for the description to explain. The schema coverage is 100% (vacuously, with no properties), and the description fully captures what the tool returns (version info).

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 explicitly states the tool shows the current MCP platform and adapter versions. This is a specific verb-resource pairing that clearly distinguishes it from 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?

No explicit guidance on when to use this tool, but as a version-inquiry tool its context is obvious. However, it doesn't mention that it's the right tool for troubleshooting version-related issues or when to prefer other diagnostics.

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 aligns with the annotations: it returns state information without indicating any side effectschen. The annotations include readOnlyHint: true, which matches the read-only nature described. No contradictions, and the description is clear about what the tool does not mutate.

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, informational sentence that lists all the key points (installed MCPs, connection status, accounts, tool counts). It is concise yet complete, avoiding any verbosity while covering all relevant aspects.

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 parameterless read-only info tool, this description is fully adequate. It covers the scope of the returned information and implies no side effects. The annotation (readOnly) further supports completeness, and no additional details are needed.

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 (empty properties in the schema), so the description accurately covers all of them. There is nothing undocumented, and the description fully describes the output.

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 explicitly states what the tool returns: 'installed MCPs, their connection status, the accounts connected to each one, and how many catalog tools each exposes.' This is precise and unambiguous, leaving no doubt about the tool's purpose.

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 focuses on what the tool returns rather than when to use it. While it's implied to be used for checking the toolkit's state (e.g., after connecting MCPs), no explicit usage context or prerequisites are mentioned. Given the tool's simplicity and read-only nature, this is adequate but could be slightly improved.

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