Prefeitura PE Recife: Certidão Negativa de Débitos

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

The description adds substantial context beyond annotations: it explains the token is a JWT, that the connection is 'permanent, non-expiring' when configured, and that calling with no args returns a login link. This goes far beyond the annotations (readOnlyHint false, idempotentHint true) and provides crucial behavioral details about state and 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 front-loaded with the tool's purpose and flows logically from permanent to session-login use cases. It's slightly run-on with multiple clauses separated by colons and commas, but every sentence adds value without 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 tool with only one optional parameter and no output schema, the description covers all necessary aspects: setup, invocation (with and without token), configuration persistence, and example invocation. It anticipates user needs around security and session permanence. No output schema exists, so no return-value documentation is expected.

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?

Despite 0% schema description coverage, the description fully explains the single 'token' parameter: it's an optional JWT used for session-only login, and omitting it returns a login link. It also explains workflow context (paste token) that the schema lacks, effectively compensating for the schema's lack of annotations.

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: 'log in in the browser, copy the access token' for MCP.AI. It specifies the resource (IDE agents like Cursor) and provides a concrete verb-noun structure. It distinguishes itself from siblings like 'connect' by focusing on authentication via browser login and token exchange.

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 explains when to use the token parameter vs no arguments ('call with { token: "<jwt>" } after the user pastes, or with no args to get the link') and differentiates permanent (config) vs session-based login. However, it doesn't explicitly contrast with alternative sibling tools like 'connect', so it stops slightly short of full when/not 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 read-only and idempotent hints, and the description adds useful context about return values in both connected and missing-credential scenarios. It doesn't contradict annotations and provides clarity on what the tool does without 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 two sentences, front-loaded with the core function ('Returns connection status and URLs'), and includes essential conditional details without fluff. Every sentence 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 (no parameters, no output schema), the description fully explains the return values in both possible states. It covers the complete behavior an agent needs to know 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?

The tool has zero parameters, so the baseline is 4. The description doesn't need to elaborate on parameters, and the schema coverage is trivially 100%.

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 output fields (authenticated, pending[], connect_url). It distinguishes itself from siblings like authenticate (which performs auth) and marketplace by focusing on status reporting.

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 explains conditional behavior based on provider connection state (connected vs missing credentials), which implicitly tells when to use it. However, it doesn't explicitly mention when not to use it or name alternative tools, so it falls short of full explicit 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 indicate openWorldHint=true and readOnlyHint=false, but the description adds rich behavioral context: invoke runs tools without installation, may return connect/checkout links for auth/payment, writes require workspace owner/admin, and actions like install/uninstall/subscribe/cancel have side effects. This goes well beyond the sparse annotations, providing transparency about permissions, execution model, and failure paths.

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 long paragraph (~300 words) but is densely packed with essential information, including a clear flow (search→describe→invoke) and key distinctions (invoke vs install). It is front-loaded with the core flow and emphasizes the most critical insight (invoke works without installation). While not broken into sections, it efficiently covers all functionality without wasted words. The length is justified by the fourteen actions plus prompt library.

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, 14 actions, no output schema), the description is remarkably complete. It covers the core interaction model, permission requirements, failure handling (connect/checkout links), distinctions between installed_in_toolkit and installed_in_workspace, and the prompt library. It explains all major behaviors and what to expect, making it sufficient for an agent to use the tool effectively across its many modes.

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 does not explain any of the 23 parameters directly. While it mentions actions (e.g., 'action=search'), it never maps specific parameters like 'query', 'mcp_id', 'tool_id', or 'arguments' to their roles. The description focuses on the tool's purpose and flow rather than parameter usage, leaving an agent to infer which fields to populate for each action. This is a significant gap given the tool's complexity.

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 this is the official mcp.ai marketplace, acting as both catalog and runner for MCPs. It explains the core flow (search→describe→invoke) and distinguishes itself from siblings like authenticate, connect, and toolkit_info by focusing on marketplace-specific actions. The verb 'marketplace' is a noun but the description thoroughly defines its role, making purpose unmistakable.

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?

Explicit guidance is provided: use search to discover, describe to inspect, invoke for one-off runs, install only for permanent additions, and list_tools to see current callables. It clearly contrasts invoke vs install and covers the prompt library separately. This gives an agent clear decision rules for when to use each action, meeting the dimension fully.

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 valuable behavioral context beyond the annotations: no platform credentials needed, prepaid credit billing, public non-confidential data, and customer responsibility under LGPD. This supplements the readOnlyHint and idempotentHint with operational and legal details, though it does not cover rate limits or failure modes.

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 appropriately sized, with the main purpose stated first and additional context in the following sentences. It covers purpose, hosting, billing, and legal responsibility without verbosity, though the final LGPD sentence could be seen as slightly tangential.

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 provides good operational and legal context (billing, LGPD, public data) but omits any mention of the return value, which is significant given the absence of an output schema. The lack of parameter documentation further reduces completeness for a tool with only three fields.

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, and the description does not explain what CPF, CNPJ, or inscrição mean or when to use each. The agent would be completely in the dark about how to populate the required 'inscricao' field or choose between CPF and CNPJ.

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 official negative debt certificate (CND) from Recife's city government, using specific language like 'consulta em fonte oficial.' It is easily distinguishable from generic sibling tools such as 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?

The description implies usage for CND queries and provides context about billing (pay-per-query) and LGPD, but it does not explicitly state when to use this tool versus alternatives or when not to use it. The guidance is implicit rather than explicit.

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 idempotent (idempotentHint: true) and non-destructive (destructiveHint: false). The description adds behavioral context by instructing to include the conversation array for reproduction, which clarifies the tool's reliance on conversation data. It does not contradict the annotations—the idempotency claim is consistent with a report action (though duplicates could be a concern, the annotation is authoritative).

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, consisting of two short sentences. It front-loads the purpose immediately and adds a single critical usage hint. There is no fluff or redundancy, making it 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?

With no output schema, the description should explain what the tool returns or the outcome of the action. It does neither. Additionally, it only partially documents parameters, leaving 'message' and 'context' undefined. Given the tool's simplicity, it still lacks essential return-value info and parameter coverage, making it incomplete for an agent to use confidently.

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 (include recent messages for reproduction) but does not clarify 'message' (though it's implied as the report content) or 'context' (which has a default but no explanation). This leaves two of three 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 states the tool's purpose: 'Report a bug, missing feature, or send feedback.' This is a specific verb (report) with clear resources (bug, missing feature, feedback), and it distinguishes itself from sibling tools like show_version or authenticate by its focus on issue reporting.

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 (when a bug, missing feature, or feedback is encountered) and mentions a required action (including the conversation array for reproduction). However, it does not explicitly name alternatives or state when not to use it, but the sibling tools are so distinct that the usage context is unambiguous.

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=false, so the description need not repeat safety. However, it adds no extra behavioral context (e.g., output format, network calls) beyond the one-line purpose. It is consistent with annotations, so 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?

The description is a single, front-loaded sentence containing zero filler. It conveys the essential purpose without unnecessary detail, earning a top score.

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 read-only tool with no parameters and no output schema, the description completely captures what the tool does. There are no missing prerequisites, side effects, or return-value expectations to clarify.

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, so the schema coverage is 100% vacuously. Per guidelines, 0 params merits a baseline of 4. The description correctly refrains from inventing parameter details, and there is nothing for it to compensate for.

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 shows the current MCP platform and adapter versions, using a specific verb and resource. It is distinct from siblings like connect or authenticate, though it partially overlaps with toolkit_info without explicitly differentiating, so not a perfect 5.

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 (i.e., when you need version information) but does not explicitly contrast with alternatives like toolkit_info or provide any exclusion criteria. For a trivial version-check tool, this is acceptable but not fully explicit.

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 this as read-only (readOnlyHint: true) and non-destructive (destructiveHint: false), so the safety profile is clear. The description adds value by disclosing the specific types of information returned (installed MCPs, connection status, accounts, catalog tool counts), which the annotations do not cover. This extra detail helps the agent predict what the tool will report without contradicting 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, well-structured sentence that lists all key information categories. It is front-loaded with the verb 'Returns' and covers all relevant aspects without padding. Every word contributes to the meaning, making it exceptionally concise and easy to parse.

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 is a read-only status reporter with no parameters, the description sufficiently covers the essential aspects: what it returns and what categories are included. It does not describe the format or structure of the returned data (e.g., whether it's a nested object), but the absence of an output schema means the agent relies on the description for that info. The listing of four specific categories compensates for the lack of schema, though the description could hint at the structure (e.g., list vs. object) to be fully 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 schema coverage is trivially 100%. The description does not need to explain parameters; it correctly focuses on what the tool returns. Since there are no params, the description's clear outline of the output fields (installed MCPs, connection status, accounts, catalog tool counts) provides all necessary semantic 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 states the tool's function: returning the current toolkit state, including installed MCPs, connection status, connected accounts, and catalog tool counts. It uses a specific verb ('Returns') and resource ('current toolkit state'), which distinguishes it from sibling tools like 'authenticate' or 'connect' that handle authentication 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 does not explicitly explain when to use this tool versus alternatives, but it implies it should be used when an agent needs an overview of the toolkit's configuration and connectivity. Without explicit exclusion of cases where other tools like 'authenticate' or 'connect' would be more appropriate, it remains somewhat implicit but adequate for a status-check tool.

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