Prefeitura AP Santana: Certidão Negativa de Débitos

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

The annotations declare readOnlyHint=false and idempotentHint=true, and the description adds useful context about the browser login flow and the non-expiring nature of the config-based approach. It does not repeat the annotations, and the description aligns with the idempotentHint (calling it repeatedly is acceptable). The only minor gap is the lack of explicit error or edge-case behavior, but it is not required here.

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, focused sentence that front-loads the user base ('MCP.AI for IDE agents'), then provides a clear sequence of actions. Every clause adds value, and the structure guides the reader from the permanent config approach to the session-only alternative in a logical order.

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 (one optional string parameter, no output schema), the description covers the necessary context: the browser login flow, the permanent vs. session-only trade-off, and the no-args invocation. It could slightly benefit from mentioning what happens after login (e.g., where the token is stored), but the coverage is arguably sufficient for normal use.

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 one optional 'token' parameter, and schema description coverage is 0%, meaning the description must compensate. The description explains that the token parameter is for pasting the JWT and that no args is allowed to get the link. This adds semantic meaning beyond the bare schema type, but the explanation is somewhat implicit. The score is 3 because it covers the main use case but doesn't exhaustively document all nuances (e.g., error handling).

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 authenticates by logging into a browser and copying an access token. It uses specific verbs like 'log in' and 'copy', and distinguishes its purpose from sibling tools by explicitly framing it for IDE agents, though it does not explicitly contrast with each sibling.

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 explicit when-to-use guidance: it tells users to add the token to the server's config for a permanent connection or to pass it as a session-only argument. It also explains the no-args fallback for getting the link, effectively covering the main usage scenarios and exclusions.

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, establishing safety. The description adds value by disclosing behavioral details: when all providers are connected it returns authenticated:true with empty pending[], and when credentials are missing it returns connect_url for toolkit and per-install URLs. 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 consists of two concise sentences. It front-loads the core purpose and then provides specific behavioral details. Every sentence adds value with no redundancy or unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, but the description clearly enumerates the return values and states (authenticated:true/pending[] vs connect_url). Given the tool's simplicity (no parameters), the description is fully self-contained and answers the agent's likely questions about 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 schema description coverage is 100%. Per the rubric, a baseline of 4 is appropriate for zero-parameter tools. The description does not need to explain parameters since none exist.

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: 'Returns connection status and URLs.' This is a specific verb + resource, and it distinguishes from siblings like 'authenticate' by focusing on status checking rather than initiating authentication. The description also explains the output conditions, which fully clarifies the tool's role.

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 versus alternatives such as 'authenticate' or 'show_version'. It lacks explicit when-not guidance or alternative tool mentions, leaving the agent to infer appropriate usage from 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?

Beyond the annotations, the description discloses important behavioral details: invoke runs an MCP even when not installed, credential gaps return a connect link, empty-wallet paid tools return a checkout/top-up link, and writes require workspace owner/admin. These are non-obvious runtime behaviors that annotations alone do not convey.

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 and information-rich: every sentence contributes value, from the core flow to credential/wallet edge cases to permission requirements. It is one long block rather than structured bullets, but given the tool's complexity, the length is justified and the most important facts are front-loaded.

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, no output schema, sparse annotations), the description covers the major workflows and edge cases well: permanent vs one-off installation, auth/payment failure handling, owner/admin write permissions, and the prompt-library sub-system. It does not explain return formats for search/describe/list_tools or detailed payloads for cancel/report_bug/request_mcp, but the core usage contexts are adequately covered.

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 carries the burden of explaining 23 parameters. It adds meaning for core parameters like action, mcp_id, tool_id, arguments, and prompt_slug by describing the search/describe/invoke flow and prompt-library workflow. However, many parameters—immediate, tier_slug, conversation, message, report_context, request_details, cancel_reason, prompt_category, prompt_targets—remain unexplained, leaving significant ambiguity.

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 opens with a precise definition: "The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them." It clearly establishes the tool's scope and distinguishes it from siblings like authenticate, connect, and toolkit_info by enumerating marketplace-specific actions and the prompt-library feature.

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 an explicit core flow: "action=search discovers MCPs by intent → describe returns one MCP's full profile ... → invoke RUNS that tool." It also states exclusions and alternatives: "Use install only to make an MCP PERMANENT ... prefer invoke for a single/occasional use," and differentiates subscribe/cancel, report_bug, request_mcp, and prompt-library actions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: it's hosted by the platform without credentials, requires payment per query, accesses official non-confidential data, and assigns LGPD data-controller responsibility to the client. This goes beyond the annotations 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 compact and front-loads the purpose ('Certidão Negativa de Débitos, consulta em fonte oficial'). It includes necessary operational and legal context (payment, credentials, LGPD) without excessive verbosity. Each sentence adds meaningful information, though it could be slightly more 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?

The description covers the tool's purpose, payment, data source, and privacy responsibilities, but lacks details about parameter usage (e.g., which identifier to provide) and expected output or edge cases. Since there is no output schema and the description doesn't clarify return values, completeness is moderate. It is a minimum viable description for a simple lookup tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema lists 'cpf' and 'cnpj' as optional strings, but the description gives no guidance on how to use them (e.g., either can be provided, at least one is needed, what they represent beyond being identifiers). Since schema coverage is 0% and no parameter details are given, the agent must infer from names alone, which is insufficient for proper usage.

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: 'Prefeitura AP Santana: Certidão Negativa de Débitos, consulta em fonte oficial' — a specific verb (consulta) and resource (CND from a specific prefecture). It is precise and distinct from the generic sibling tools (authenticate, connect, etc.), making it 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 conveys that this is for querying official Brazilian data (CND) and mentions it's read-only without platform credentialsikuha, which clarifies context. However, it doesn't explicitly compare with alternatives or state when not to use it. Given the sibling tools are generic (authenticate, marketplace, etc.), the usage context is sufficiently clear, but no exclusions are provided.

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 provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds that the conversation array is for reproduction, but doesn't describe other behavioral aspects like side effects or result. It doesn't contradict 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?

Two sentences, front-loaded with purpose. 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?

For a simple tool with 3 params and no output schema, the description covers the key usage instruction (include conversation) but doesn't elaborate on return behavior or other param purposes. However, it's adequate.

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 0% coverage; description only hints at the 'conversation' parameter but doesn't explain 'message' or 'context' meaning beyond the main verb. It partially compensates but not fully.

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 purpose: 'Report a bug, missing feature, or send feedback.' This is a specific verb+resource that distinguishes it from sibling tools like authenticate or show_version, which obviously serve different functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

While there are no explicit when/not guidance, the description implies usage for reporting issues and instructs to include the conversation array for reproduction, which gives context. Since there are no similar tools among siblings, exclusions aren't necessary. Clear enough to choose correctly.

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 read-only, idempotent, and non-destructive behavior. The description adds specificity by naming the exact information returned (platform and adapter versions), which is useful context beyond the generic tool name. It does not contradict any annotations and provides additional detail about the tool's output.

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 conveys all necessary information without any filler. It is front-loaded and efficiently states the tool's purpose.

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 no parameters and no output schema, the description is sufficient to inform an agent of the tool's purpose. It could be enhanced by describing the return format, but for a simple version check, the current description is adequate. The annotations provide safety 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?

There are zero parameters, and schema coverage is 100% (no properties). The description adds no parameter information because none are needed. Baseline for 0 params is 4, 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 displays the current MCP platform and adapter versions, using a specific verb ('show') and resource (versions of platform and adapter). This distinguishes it from sibling tools like connect or authenticate, which have 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 implies usage for checking version information. While it doesn't explicitly state when not to use it or mention alternatives, the context makes it obvious that this is the tool to call for version details. No exclusions or alternative recommendations are provided.

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 fully disclosed. The description adds that it returns counts and connection status, which is beyond the annotations, but it doesn't elaborate on return format or potential delays if connections are checked live. This is adequate but not rich, hence a 3.

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, yet it conveys the tool's purpose and content comprehensively. Every clause adds specific detail (installed MCPs, connection status, accounts, catalog tool count), with no filler or redundancy. It is front-loaded and 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?

Given the tool has no parameters, no output schema, and a simple informational purpose, the description is sufficient to understand its functionality. It doesn't exactly specify the output format (e.g., whether it's a list or graph), but for a state inspection tool, the core information is complete. A 4 is appropriate.

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 covered (100%). The description adds no parameter-specific info because none exist, but it clearly specifies the tool's output scope, which is the only meaningful semantic here. Baseline 4 applies for zero-parameter 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 clearly states the tool returns the current toolkit state, specifying exactly what it contains: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly distinguishes it from siblings like connect or marketplace, as it is an informational snapshot rather than an action.

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 implies when to use it: to inspect the toolkit state, which is likely useful before or after connecting or troubleshooting. While it doesn't explicitly state when not to use it, the context is clear given the sibling names and the tool's read-only nature, so it earns a 4.

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