Prefeitura MG Belo Horizonte: Certidão Negativa de Débitos

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

The description does not conflict with annotations (readOnlyHint: false), and it adds behavioral context about permanent vs. session-based authentication. However, it falls short of disclosing side effects such as token storage, overwrite behavior, or error handling. As annotations only note idempotency and non-read-only, the description partially covers new ground but leaves gaps.

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 moderately dense and front-loaded with the tool's purpose, but reads as a long run-on sentence with multiple clauses and instructions. The use of colons and the 'Best:' phrase help, yet it could be broken into clearer steps or bullets to reduce cognitive load.

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 there is only one optional parameter and no output schema, the description delivers adequate context: it covers both invocation methods and the recommended setup. It might benefit from stating expected outcomes or subsequent steps, but overall it is well-adapted to the tool's simplicity.

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, the description takes on full responsibility and effectively explains the token parameter: optional, used to paste JWT, or omitted to get a link. It clarifies the parameter structure inline. However, it could be clearer about the expected format or constraints.

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 explains that this tool authenticates by providing a token or returning a login link, with specific verbs and resources. However, the phrase 'MCP.AI for IDE agents' is cryptic and may confuse the reader. It distinguishes itself from siblings like 'connect' by detailing the token flow, but it could be more explicit about being the login entry point.

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 scenarios: recommended permanent header config, session-only token paste, and no-args call to retrieve a link. Delineates options for the agent on how to proceed. However, it lacks explicit 'when not to use' and does not mention alternatives or comparisons to 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, indicating a safe read operation. The description adds valuable context about response behavior: returning authenticated:true with empty pending[] when all providers are connected, and connect_url when credentials are missing. This provides insight beyond the annotations without 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 only two sentences, front-loaded with the core purpose ('Returns connection status and URLs'), and then provides conditional details. Every sentence adds value without fluff 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 status tool with rich annotations (readOnly, idempotent) and no output schema, the description covers the main response states. It does not explicitly address partial connection scenarios, but these are implied by the 'empty pending[]' condition. Overall, enough information is provided for an agent to understand tool behavior.

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 is empty. With a parameter count of 0, baseline is 4 per the rubric. The description does not need to elaborate on parameters and focuses appropriately on output behavior.

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 function with a specific verb and resource: 'Returns connection status and URLs.' It further explains conditional outcomes (all providers connected vs. credentials missing), making it easy to distinguish from sibling tools like 'authenticate' which performs an action rather than reporting 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 implies usage for checking connection status, but does not explicitly state when to use this tool over siblings like 'authenticate'. It gives context about what it returns in different scenarios but lacks direct guidance on when to choose this tool or alternatives, so usage is only implied.

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 context beyond annotations: invoke works without installation, does not bloat the tool list, returns connect links for credential needs, and returns checkout/top-up links for unpaid paid MCPs. It also discloses permission requirements for write operations and flags installed_in_toolkit vs installed_in_workspace. No contradiction with 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 long wall of text but is front-loaded with the core flow and key caveats (invoke works without install, credential/payment links). It uses helpful markers like 'KEY:' and semicolons to pack in necessary detail. It earns most of its length given the tool's breadth, though it could be better organized with bullet points or action groupings.

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 (14+ actions, 23 params, no output schema, no parameter descriptions), the description covers a remarkable amount: the discovery-to-invoke flow, one-off vs permanent installation, auth/billing edge cases, permissions, the prompt library, and sibling distinctions. It is not fully complete—search/describe return formats and some prompt-related parameters are unspecified—but it is adequate for an agent to select and invoke the tool correctly in most cases.

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 23 parameters and 0% schema description coverage, the description carries a heavy burden. It explains the meaning of many action enum values (search, describe, install, invoke, search_prompts, etc.) and clarifies tool_id's role in the invoke flow. However, it does not explain most individual parameters like limit, query, arguments, immediate, tier_slug, conversation, prompt_vars, or report_context, leaving significant gaps.

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 both a catalog of MCPs/tools and a runtime for executing them, with a concrete flow: search → describe → invoke. It differentiates the tool's broad role from siblings like authenticate/connect and lists distinct sub-actions (search, describe, install, invoke, prompt library) with specific 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?

Explicit usage guidance is given: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT in the active toolkit.' It also explains when to use request_mcp, list_tools, subscribe/cancel, and report_bug, and notes that writes require workspace 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?

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds meaningful context: it mentions the tool is paid (with prepaid credit), requires no platform credentials, and handles non-confidential data. It also discloses LGPD compliance. This goes beyond the annotations and informs the agent about cost and data sensitivity, which is valuable for behavior decisions.

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 moderately concise, with three sentences. The first sentence states the purpose, the second explains cost and credentials, and the third adds legal/privacy disclaimers. While not overly verbose, the LGPD paragraph adds legal jargon that may not be essential for immediate tool usage, making it slightly less efficient than ideal.

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?

Despite having two parameters and no output schema, the description fails to explain the parameters, which is a critical gap. It does provide context about the data source, cost, and confidentiality, but omits how to use the CPF/CNPJ inputs. For a simple query tool, this incompleteness prevents an agent from correctly assembling the request.

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 two string parameters (cpf, cnpj) with zero description coverage. The description does not explain these parameters, their usage, or how they relate to the query. It does not state that one or the other is required, nor does it clarify input formats. Since schema coverage is 0%, the description must compensate but fails to do so, leaving the agent without sufficient information to correctly invoke the 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: querying a Certificate of Negative Debts (Certidão Negativa de Débitos) from Belo Horizonte City Hall. It uses the verb 'consulta' (query) and specifies the resource, distinguishing it from generic sibling tools like 'authenticate' or 'marketplace'. The mention of 'fonte oficial' (official source) adds specificity.

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 some context (when to use: for official Brazilian government data queries, specifically this certificate) but does not explicitly state when not to use it or mention any alternatives. It focuses on operational aspects like payment and legal compliance rather than usage scenarios. Since there are no similar sibling tools, exclusion criteria are absent, but the guidance is still weak.

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 include readOnlyHint: false, destructiveHint: false, and idempotentHint: true, which already convey the tool's side-effect profile. The description adds the detail that the conversation array is needed for reproduction, which is useful context beyond the schema. It does not contradict annotations, but it does not elaborate on potential side effects (e.g., whether feedback is submitted permanently) or return behavior. Given the annotations are present, the description adds incremental value without redundancy.

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, compact sentence that immediately states the purpose and then adds the key usage instruction. It is front-loaded, free of redundancy, and every word earns its place. There is no filler or unnecessary detail.

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 has 3 parameters, no output schema, and no annotations describing return values. The description fails to explain all parameters (especially 'context') and does not hint at what the tool returns or confirms after reporting. While the core purpose is clear, the description is incomplete for an agent that needs to invoke the tool correctly and interpret the result. The gap in parameter semantics and return behavior reduces completeness.

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 tool description must compensate for the lack of parameter documentation. The description only mentions the 'conversation' parameter explicitly ('Include the conversation array...'), while leaving 'message' (required) and 'context' unexplained. The purpose of 'message' is inferable from the tool name, but 'context' remains ambiguous. This partial coverage leaves significant gaps for parameter understanding.

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.' It uses a specific verb ('Report') and specifies the resource (bug/missing feature/feedback), distinguishing it from unrelated sibling tools like authenticate, connect, and marketplace. The scope is explicit and 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 what to do ('Report a bug... send feedback') and even gives a usage hint ('Include the conversation array with recent messages for reproduction'). However, it does not explicitly mention when NOT to use this tool or direct users to alternatives, though none of the sibling tools serve a similar function. The single-sentence instruction effectively communicates the intended use case.

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, covering the safety profile. The description adds meaningful context by specifying the tool reports 'MCP platform and adapter versions,' which goes beyond the tool name. No side effects or special behaviors need disclosure given the read-only, idempotent nature.

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 single, declarative sentence front-loads the action and object. Every word contributes; there is no redundancy or 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?

Given the tool's simplicity—no parameters, no output schema, and clear sibling distinction—the description fully equips an agent to misuse or misuse it. No return value documentation is required, and the behavior is fully captured.

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 zero parameters, the schema is trivially 100% covered. The description doesn't need to explain parameters, and no ambiguity exists. This aligns with the rubric's baseline of 4 for parameterless tools.

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 'Show' and clearly identifies the resources ('current MCP platform and adapter versions'), leaving no ambiguity about the tool's function. It differentiates itself from siblings like 'report_bug' and 'toolkit_info' by focusing on version information, which is a distinct 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?

No explicit when-to-use or alternative guidance is given, but the tool's trivial nature (zero parameters, read-only version check) makes its usage self-evident. Context implies it should be used to inspect current versions, though explicit mention of when not to use it (e.g., vs. 'toolkit_info') would have been clearer.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds 'current' state, implying a snapshot. It does not disclose additional behavioral aspects like potential delays, error conditions, or the format of the returned data. Given the annotations handle the main safety aspects, the description adds some value but not much 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 single sentence that is concise and front-loaded with the main action. It lists the key items returned without any unnecessary filler, making it efficient and well-structured.

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—zero parameters, read-only, and no output schema—the description fully explains what the user gets: the toolkit state including MCPs, statuses, accounts, and catalog tool counts. There is no ambiguity or missing information for a typical use case.

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 coverage is trivial (100% since no params). According to the rules, for 0 params the baseline is 4. The description does not need to explain parameters because there are none. It accurately focuses on the output, which is the state information.

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 verb ('returns') and the resource ('current toolkit state') and enumerates specific contents (installed MCPs, connection status, accounts, catalog tool counts). This unambiguously distinguishes it from siblings like show_version (version info) and connect (establishing connections), 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 about what the tool returns, implying it should be used for querying overall toolkit health and connectivity. However, it does not explicitly mention when to use it over alternatives, such as 'use show_version for just the version' or 'use connect to establish a connection'. There is no exclusionary guidance, but the nature of the tool makes its usage fairly obvious.

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