Prefeitura MG Janaúba: Certidão Negativa de Débitos

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

Annotations already indicate idempotent and non-destructive, but the description adds valuable context: it explains the permanent vs. session-only nature, that calling with no args returns a link, and that pasting a token authenticates for a session. This goes beyond structured data.

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 long but well-structured with a colon and two clear options. Every sentence earns its place, and the most important information is 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?

The tool is simple and the description covers the main contexts (permanent config vs. session token). It doesn't mention return values, but no output schema exists and the flow is understandable without it.

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 fully carries the burden. It explains the 'token' parameter as a JWT, shows how to pass it, and clarifies the no-args case. This is exactly what an agent needs.

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: authenticate to MCP.AI for IDE agents. It specifies the process (log in via browser, copy access token) and distinguishes this from siblings by focusing on the authentication flow for agents like Cursor.

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 alternatives (permanent via config header vs. session-only via token) and clear instructions for each. It lacks an explicit 'when not to use' statement, but the guidance is strong.

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 read-only and idempotent behavior. The description adds genuine transparency by explaining conditional response patterns: what happens when all providers are connected ('returns authenticated:true and empty pending[]') versus when credentials are missing ('returns connect_url'). This goes beyond the annotations and provides actionable behavioral expectations.

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?

Three sentences, no fluff. The primary action is front-loaded, followed by two conditional scenarios. Every clause adds value, and the structure is easy to parse quickly.

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, read-only status endpoint, the description covers the essential scenarios: successful connection and missing credentials. It doesn't elaborate on the exact structure of URLs or the meaning of 'providers,' but this feels acceptable given the tool's simplicity and the safety guarantees from annotations.

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 of 4 applies. The description wisely skips parameter details and focuses on response semantics, which is appropriate here. No points lost since there is nothing to clarify.

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 clear, specific verb+resource pairing: 'Returns connection status and URLs.' It leaves no ambiguity about what the tool does and implicitly distinguishes itself from siblings like 'authenticate' and 'marketplace' by focusing on status retrieval.

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?

Usage is implied: the agent can infer this is the tool for checking connection status, but there is no explicit 'use this when...' or comparison to alternatives. No exclusions or 'instead of' guidance is given, leaving the agent to reason 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 minimal annotations (readOnlyHint false, openWorldHint true), the description discloses key behaviors: invoke works even when the MCP is not installed ('runs the tool pontualmente'), returns connect/checkout links on credential or payment needs, and that writes require workspace owner/admin. It also explains the one-off nature of invoke and the permanent nature of install. This significantly adds behavioral context that annotations do not contain.

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 about 180 words, long but justified given the tool's complexity. It is front-loaded with the core concept and flow, then details key behaviors and specific actions. Each sentence adds value—no fluff. The structure is logically ordered (concept → flow → key nuances → actions). It is appropriately sized for a meta-tool with 14 actions, though it could be broken into sections for easier scanning, earning a 4.

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 high complexity (23 parameters, 14 actions, no output schema), the description provides a strong overview covering all key aspects: the marketplace core, invoke/install distinction, auth/payment handling, prompt library, and permission requirements. It does not detail response structures for every action, but it does mention what returns (e.g., describe returns full profile, publish_prompt returns a shareable link). It is reasonably complete for the scale, though an output schema or per-action response examples would improve it, hence 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?

With a 0% schema description coverage, the description must compensate heavily. It links major parameters to actions: 'action=search', 'describe returns one MCP's full profile', 'invoke RUNS that tool with tool_id and arguments.' It also mentions prompt-related parameters (prompt_body, prompt_vars) implicitly in the prompt library section. However, it does not explicitly explain every one of the 23 parameters (e.g., prompt_targets, cancel_reason), though it gives enough context for the agent to infer from the action descriptions. The description adds substantial meaning but leaves some parameter details implicit, scoring 4.

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: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It goes beyond a generic statement by detailing the core flow (search → describe → invoke) and listing specific actions (install, subscribe, search_prompts, etc.), which distinguishes it from sibling tools like connect or report_bug. The verb+resource combination is precise 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 explicit guidance on when to use different actions: 'Use install only to make an MCP PERMANENT in the active toolkit... prefer invoke for a single/occasional use.' It also specifies that 'list_tools lists what is callable right now' and that writes require admin. The alternative is clearly stated: 'prefer invoke for a single/occasional use' vs 'install only to make an MCP PERMANENT.' This offers clear context 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 and destructiveHint=false. The description adds valuable behavior context: it is a paid query using prepaid credit, requires no platform credentials, retrieves the same non-confidential data available to citizens, and imposes LGPD controller obligations on the client. 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 short and front-loaded: the first sentence states the core purpose. The final LGPD/controller sentence is contextually relevant but slightly boilerplate; still, overall it is compact and without significant waste.

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 context around payment, credentials, and data sensitivity, but it is incomplete for invocation: it lacks guidance on how to provide CPF/CNPJ/certificate code and gives no hint of the response format. With no output schema and three undocumented parameters, the tool is not fully specified.

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 description provides no explanation of cpf, cnpj, or codigo_certidao. It does not say which identifiers are needed, whether any combination is required, or how the certificate code relates to the query. The name itself implies a certificate query, but the description adds no parameter-level meaning.

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 resource ('Prefeitura MG Janaúba: Certidão Negativa de Débitos') and the action ('consulta em fonte oficial'). This is a specific, well-scoped query tool, and it is easily distinguished from the generic sibling tools like authenticate, marketplace, or 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?

The description gives clear context on when to use it: to query the official CND from Janaúba/MG, with prepaid credit and no platform credentials. It does not explicitly name alternatives or state when not to use, but the use case is defined well enough for a focused data-query tool.

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 inform the agent that the tool is idempotent and non-destructive (idempotentHint=true, destructiveHint=false). The description adds useful reproduction guidance ('Include the conversation array with recent messages for reproduction') but does not disclose any extra behavioral side effects or limitations beyond that.

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 that immediately states the purpose and then gives the one key operational instruction. No filler or unnecessary repetition.

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 a single required string parameter and low expected complexity, the description covers the core use case and the important reproduction hint. It is slightly incomplete around the exact meaning of the remaining optional parameters and the mismatch between description and schema for 'conversation', but overall the tool is sufficiently describable in one sentence.

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 provides zero description coverage, so the description must carry the parameter interpretation. It explains that 'conversation' should include recent messages for reproduction, but incorrectly calls it an 'array' while the schema defines it as a string (likely a serialized JSON array). The 'message' and 'context' parameters receive no explanation beyond their names and defaults.

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 ('Report') and the possible resources ('a bug, missing feature, or feedback'). It is specific and distinct from sibling tools like authenticate, show_version, and marketplace, 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?

It clearly indicates when to use the tool: whenever a bug, missing feature, or general feedback is intended. It does not explicitly name exclusions or alternative tools, but the context is unambiguous and no competing sibling exists for this purpose.

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 provide readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds that it shows both platform and adapter versions, which is useful context 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?

A single sentence with no filler, front-loaded purpose. Perfect conciseness.

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 version-check tool with no parameters and an output schema absent, the description adequately conveys what the tool doesched. It mentions the specific versions shown, which is enough for an agent to select and invoke it.

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, so no param semantics needed. The description is sufficient; baseline is 4 for zero params.

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 action: 'Show the current MCP platform and adapter versions.' It is specific about what resource (MCP platform and adapter versions) and distinguishes it from other tools 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?

The description implies usage (to check versions) but does not explicitly state when to use it or when not to. Since there are no alternatives for version checking, it is adequate but could be more 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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe read. The description adds behavioral value by disclosing what 'toolkit state' means: installed MCPs, connection status, accounts, and catalog tool counts. This is a good example of the description supplementing the annotations, not contradicting them. It doesn't disclose potential latency or whether connection status is live, but for a recursive info tool, this is appropriately transparent.

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 covers what the tool returns without wasted words. Every clause earns its place: 'installed MCPs,' 'connection status,' 'accounts connected to each one,' and 'catalog tools each exposes.' No fluff, perfectly scoped.

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, read-only info tool with no output schema, the description completely captures the return payload. It doesn't need to enumerate return formats since there's no output schema, and for an agent needing toolkit state, the description is unambiguous. The tool is a trivial introspection command, and the description is perfectly calibrated to that complexity.

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 parameters and baseline score 4 for parameter semantics, the description is not required to add parameter info. The description focuses on return-value semantics instead, which is appropriate since there are no parameters. No deduction needed since there are no parameters left undocumented.

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 a clear specific verb 'Returns' with a specific resource 'current toolkit state' and details what it contains (installed MCPs, connection status, accounts, catalog tools). It distinguishes from siblings like 'show_version' and 'marketplace' by focusing on MCP/account/catalog tooling rather than version or marketplace information.

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: when an agent needs information about installed MCPs, their connection status, connected accounts, or catalog tool counts. It doesn't explicitly name alternatives or when-not-to-use, but the sibling-context and 'current toolkit state' framing provides clear context for when this is the right tool versus others like 'marketplace' or 'show_version'. A point is deducted for not explicitly calling out alternatives.

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