Prefeitura BA Ilheus: Certidão Negativa de Débitos

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

Annotations indicate idempotentHint=true and destructiveHint=false, which the description aligns with. The description adds behavioral context: it explains that calling with no args returns a link, and that pasting a token provides session-only login. It also mentions the permanent config option. This goes beyond the annotations, though it doesn't detail side effects like token validation or error handling.

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, two sentences, and front-loads the purpose. It packs a lot of information efficiently: the target audience, the login method, the two usage modes, and the config alternative. No wasted words, though the structure could be slightly clearer with bullet points, but it's acceptable.

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 parameter, no output schema), the description is fairly complete. It covers the main use cases and the alternative permanent setup. It doesn't explain what happens after authentication (e.g., how the token is used), but that's beyond the tool's scope. The sibling tools like 'connect' might be related, but the description doesn't need to address them.

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 parameter 'token' with no description, and schema description coverage is 0%. The description explains the token parameter's purpose: it should be a JWT pasted by the user for session-only login. This adds meaning beyond the schema, but it doesn't specify the token format beyond 'jwt' or any constraints. Since there's only one parameter and it's optional, the description compensates reasonably.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to authenticate an IDE agent by logging in via browser and obtaining an access token. It distinguishes between two usage modes (permanent config-based and session-only). However, it doesn't explicitly contrast with sibling tools like 'connect', though the context suggests it's the authentication 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?

The description provides explicit guidance on when to use this tool: after the user pastes a token, or with no args to get a login link. It also explains the alternative of adding the token to the server's config for a permanent connection, which is a clear usage guideline. It doesn't mention when not to use it, but the context is clear enough.

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 behavioral details beyond the annotations: it specifies the exact return values ('authenticated:true and empty pending[]') and the conditional presence of 'connect_url' and 'per-install URLs'. This complements the readOnlyHint and idempotentHint 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 two sentences, front-loaded with the primary purpose, and every sentence adds value by describing state-dependent behavior. It is concise and well-structured without unnecessary 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, read-only), the description is complete. It explains the primary output and how it varies under different conditions, which is sufficient for an agent to select and invoke the tool 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 accepts no parameters, so the schema coverage is trivially 100%. The description does not need to explain parameter semantics, and with zero parameters, the baseline score is 4. No additional parameter information is required.

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.' This is a specific verb (returns) with a clear resource (connection status), and it distinguishes itself from sibling tool 'authenticate' by focusing on status rather than performing authentication.

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 this tool: to check connection status and get relevant URLs. It also explains behavior in different states (all connected vs. missing credentials), but does not explicitly name alternatives or provide exclusionary 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 are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the description carries the behavioral burden and does so excellently. It discloses that invoke runs tools even when MCPs are not installed, returns connect links for credential needs and checkout links for payment, and requires owner/admin for writes. No contradiction with annotations; description adds rich context.

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 front-loaded with purpose and flow, but it is quite long (over 200 words). It includes some repetition, such as 'pontualmente (one-off)' and 'prefer invoke for a single/occasional use,' which could be tightened. Nevertheless, the length is justified by the tool's complexity and the need to explain multiple action types and the 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 params, 14 actions, no output schema), the description is remarkably complete. It covers the entire workflow, mentions error-handling scenarios (connect link, checkout link), permission guards for writes, and the separate prompt library with its own sub-actions. It addresses all major use cases an agent would face, making it self-sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It effectively explains the core parameters (action, mcp_id, tool_id, arguments) and their roles in the flow, and covers prompt-related params (prompt_slug, prompt_vars, etc.) contextually. However, some parameters like limit, query, immediate, and tier_slug are not explicitly described, though their purpose is inferable. The description provides strong semantic grounding for the most important parameters, but does not exhaustively document all 23.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is the official marketplace and catalog for MCPs/tools, with a verb+resource structure. It thoroughly distinguishes itself from sibling tools by explaining its role as the central discovery and execution mechanism, and explicitly covers capability requests like 'find an MCP that does X' and 'is there a tool for Y'.

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, actionable guidance: core flow (search → describe → invoke) with clear when-to-use for invoke vs install, and when to use list_tools, subscribe/cancel, report_bug, and request_mcp. It also explains permission requirements for write actions and the prompt library path, giving both inclusion and exclusion criteria.

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, covering the read-only and non-destructive nature. The description adds valuable context beyond annotations: payment requirement (prepaid credit), absence of platform credentials, and LGPD data controller responsibilities. This enriches the behavioral profile 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 paragraph, efficiently front-loaded with the core purpose. It contains some repeated concepts (e.g., 'fonte oficial' and 'fontes oficiais') but is not verbose. The structure is clear, though it could be slightly more streamlined without losing meaning.

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 a simple query with two unannotated parameters and no output schema. The description fails to clarify what the result will be (e.g., a certificate document) or the required inputs. It also omits any mention of the parameter constraints, making it incomplete for effective use. With no output schema and minimal annotation, the description should have compensated but did not.

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 input schema has two parameters (cpf, cnpj) with no descriptions, and schema description coverage is 0%. The description does not mention these parameters at all, nor does it explain the format or necessity of CPF/CNPJ. With zero compensation from the description, the agent lacks essential parameter guidance, resulting in a minimal score.

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: 'consulta em fonte oficial' (consultation in official source) of a 'Certidão Negativa de Débitos' (Negative Debt Certificate) for Prefeitura BA Ilheus. It uses a specific verb (consulta) and resource, and distinguishes itself from sibling tools (authenticate, connect, etc.) by specifying the municipal domain.

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 context on usage: hosted by platform, no platform credentials required, pay per consultation with prepaid credit, and LGPD compliance. However, it does not explicitly state when to use this tool over alternatives or when not to use it. The purpose is clear enough but lacks explicit exclusions or comparisons.

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 convey idempotency, non-read-only, and non-destructive behavior. The description adds useful context by instructing to include recent conversation messages for reproduction, but it does not disclose what happens after submission, whether data is sent externally, or whether a confirmation is returned. This is acceptable but not rich given 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?

Two concise sentences, front-loaded with the primary action and followed by a key usage instruction. Every word earns its place with no redundancy or filler.

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 relatively simple with only three parameters and no output schema, but the description leaves `context` unexplained and does not describe what happens after a successful report. It covers the core purpose and one important parameter, but an agent would still need to infer how to populate the missing fields and what to expect in response.

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, but it only explains the conversation parameter's purpose ('recent messages for reproduction'). It does not clarify what `context` should contain, and it only indirectly maps `message` to bug/feature/feedback text. Additionally, calling `conversation` an 'array' while the schema declares it as a string with default '[]' creates 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 clearly states the tool's function with a specific verb: 'Report a bug, missing feature, or send feedback.' This unambiguously distinguishes it from siblings like authenticate, connect, or show_version, which have completely 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 direct usage context by telling the agent to 'Include the conversation array with recent messages for reproduction.' It does not explicitly mention alternatives or exclusions, but the sibling tools have no overlapping functionality, so the intended use is reasonably clear.

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 explicitly indicate readOnlyHint: true, idempotentHint: true, and destructiveHint: false, aligning with the 'Show' action in the description. No mutating or risky behavior is implied.

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, concise sentence that fully conveys the tool's function. No extraneous details or complex structure is needed for such a simple tool.

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 simplicity of the tool and the comprehensive annotations (read-only, idempotent, non-destructive), the description is complete. No output schema is necessary since the tool returns version info as a simple result.

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 takes zero parameters, so there are no parameter ambiguities. The schema is empty, and the description covers everything, achieving 100% coverage trivially.

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: showing the current MCP platform and adapter versions. This is unambiguous and directly reflects the tool's purpose.

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

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

The tool has no parameters and its use case is self-evident from the description. It doesn't specify when to use it, but for a simple version query, such guidelines are unnecessary.

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, idempotent, and non-destructive, and the description does not contradict them. It adds useful behavioral context by specifying exactly what state is returned, though it does not describe output format or edge cases.

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 with no filler or redundancy. Every phrase contributes meaningful information about the tool's output.

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 no output schema, the description sufficiently enumerates what the return value covers: installed MCPs, connection status, connected accounts, and catalog tool counts. For a parameterless status/introspection tool, this is complete and self-contained.

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 an empty input schema, so there are no parameter details to explain. The baseline for 0 params is 4, and the description adds no unnecessary parameter 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 uses a specific verb ('Returns') and identifies a precise resource ('current toolkit state') with enumerated details: installed MCPs, connection status, accounts, and catalog tool counts. This clearly distinguishes it from sibling tools like connect or show_version.

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 the tool is used to inspect toolkit state, but it does not explicitly state when to use it versus alternatives or mention any exclusions. This is implied usage guidance rather than explicit when-to-use/when-not-to-use guidance.

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