Procuradoria Geral do Estado BA: Dívida Ativa

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

The description adds context beyond the annotations by explaining the two authentication modes (permanent config vs session-only) and the behavior of calling with no args (returns link). It does not contradict the annotations and provides useful side-effect information.

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 slightly verbose but well-structured, with 'Best:' and 'Or' delineating options. It conveys all necessary information without excessive fluff, though it could be tightened slightly.

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 all essential aspects for using the tool: how to authenticate, the two modes, and the behavior with and without the token. Since there is no output schema, it appropriately focuses on input and usage.

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 description fully explains the 'token' parameter: it is a JWT that the user pastes, and it is optional (since calling with no args is allowed). This goes well beyond the schema, which only defines it as a string without additional context.

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

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

The description clearly states that the tool is for authentication, explaining the login process and token usage. It is distinct from sibling tools like connect or report_bug, 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 explicit instructions on when and how to use the tool: either with a token for session-only login or without args to obtain the login link. It also explains the permanent vs session-only options, giving clear usage scenarios.

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 and idempotentHint, so the description doesn't need to restate those. It adds valuable behavioral detail about conditional returns (authenticated:true when all connected, connect_url for missing credentials). This goes beyond the annotations and helps the agent anticipate outputs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose. Every clause adds value: the first defines the tool, the second explains conditional behavior. No wasted words or repetition of annotations.

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 0-param, read-only status tool, the description fully covers the return values and conditional scenarios. The output schema is absent, so the description's mention of 'authenticated:true' and 'pending[]' is necessary and sufficient. Siblings make the tool's role clear. Complete.

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

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

The tool has zero parameters, so the schema is trivially complete (100% coverage). The description doesn't need to explain parameters. Baseline for 0 params is 4, and the description provides no contradictory or redundant info.

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 'Returns connection status and URLs' with a specific verb and resource. It distinguishes this from sibling tools like 'authenticate' by focusing on status reporting rather than initiating authentication. The conditional details (authenticated:true, pending[], connect_url) make the purpose unmistakable.

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

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

The description implies usage for checking connection status, but it does not explicitly state when to use this tool versus alternatives like 'authenticate'. There's no clear when/when-not guidance, though the context makes it inferable. This is borderline between implied and explicit, so a 3 is appropriate.

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 the annotations: invoke works even when the MCP is not installed, runs one-off without bloating the tool list, returns connect/checkout links for auth/payment, and writes require workspace owner/admin. It also explains prompt-library sharing behavior. No contradiction with annotations exists.

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 but every sentence contributes meaningful guidance for a multiplexed tool. It front-loads the core purpose and flow, then covers invoke behavior, install vs invoke, permissions, and the prompt library. It could be improved with bullet structure, but it is not padded or redundant.

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), the description is remarkably complete: it explains the search→describe→invoke flow, one-off invoke behavior, auth/billing link handling, install permanence, permission requirements, and prompt-library operations. Gaps remain for the resume action, immediate/tier_slug semantics, and return-value expectations, but the overall mental model is strong.

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 adds real meaning for the action enum and core workflow (search, describe, invoke, install, list_tools, subscribe, cancel, report_bug, request_mcp, prompt actions). However, several parameters remain unexplained, including resume, immediate, tier_slug, cancel_reason/cancel_comment, arguments format, conversation, and prompt_targets, so it does not fully compensate for the schema gap.

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 specific identity: 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It clearly states the tool's core flow (search → describe → invoke) and distinguishes it from siblings by positioning it as the catalog/runner plus prompt library, not just another auth or info tool.

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 explicit usage guidance: 'prefer invoke for a single/occasional use' vs 'Use install only to make an MCP PERMANENT,' and 'list_tools lists what is callable right now.' It also explains when to use request_mcp ('when nothing fits') and describes the search/describe workflow, making alternatives 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 already provide readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond those: payment with prepaid credits, no platform credentials needed, data is not confidential, and the caller is LGPD data controller. There is 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 compact and front-loaded: first the subject/purpose, then cost and credentials, then legal/source caveats. Each sentence adds something, though legal repetition about LGPD could be trimmed.

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 important operational context (official source, cost, credentials, consent, LGPD) but lacks enough detail about input selection and output behavior. With no output schema and no parameter descriptions, the agent still has meaningful uncertainty about how to invoke it correctly.

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

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

Schema description coverage is 0%, and the description does not explain the CPF and RENAVAM parameters, their formats, optionality, or relationship to a query. Since it does not compensate for the schema gap, an agent receives almost no semantic help for the inputs.

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 explicitly states the action ('consulta') and the resource ('Dívida Ativa' from the Procuradoria Geral do Estado BA), adding that it queries an official source. This clearly distinguishes it from sibling tools like authenticate, marketplace, and show_version, and gives a concrete purpose even without reading the input schema.

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 useful context: no platform credentials required, prepaid per-query cost, official non-confidential source, and LGPD responsibility. However, it does not explicitly state when to prefer this tool over alternatives or when not to use it, so usage guidance is largely implicit.

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 declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false, so the description is not contradicted. The description adds the note about including the conversation array for reproduction, which is a behavioral context beyond the schema. However, it does not disclose side effects like storing the report or any rate limits, though given the annotations, a moderate disclosure is acceptable.

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-loaded with the main purpose. The second sentence adds essential usage detail without wordiness. Every sentence contributes to understanding the tool's function and invocation.

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 3 parameters stub and no output schema. The description covers the main purpose and one key requirement (conversation array), but does not explain expected input fields like 'message' or 'context', nor the outcome after reporting. Given the low complexity and lack of output schema, a score of 3 is appropriate—adequate but with gaps.

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 explain parameters to add value. It mentions the 'conversation array' which maps to the 'conversation' parameter, but does not explain the 'message' parameter (which is required) or the 'context' parameter. This partial explanation leaves significant gaps for an agent 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: 'Report a bug, missing feature, or send feedback.' It uses specific verbs (report, send) and identifies the resource (bug, feature, feedback), distinguishing it from sibling tools like marketplace or toolkit_info which 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?

The description provides clear context for when to use the tool (reporting issues) and advises including the conversation array for reproduction, which is practical usage guidance. However, it does not explicitly exclude alternative approaches or mention when not to use it, though the purpose 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the agent knows this is a safe, idempotent read. The description adds minimal but useful context by specifying both MCP platform and adapter versions, but it does not disclose any additional behavioral traits (e.g., caching, failure modes). With annotations covering safety, a score of 3 is appropriate.

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, tightly worded sentence that conveys the exact purpose without any filler. It is appropriately front-loaded and every word earns its place.

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

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

For a tool with no parameters, no output schema, and comprehensive annotations (readOnly, idempotent), the description is fully sufficient. It clearly states what the tool returns (current versions) and adds no unnecessary complexity. The context is complete for an agent to use correctly.

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

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

The tool has zero parameters, and the input schema is empty. Per the rubric, a baseline of 4 applies, and the description does not need to compensate for missing parameter details. No additional meaning 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 shows current MCP platform and adapter versions, using a specific verb ('Show') and precise resource. It is distinct from sibling tools like toolkit_info, which likely provides broader information, but the focus on version details is 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?

No usage context is provided. The description does not mention when to use this tool versus alternatives, nor any exclusions or prerequisites. For a simple version check, it may be self-evident, but the lack of explicit guidance means the agent gets no help in deciding between this and similar sibling tools like toolkit_info.

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 tool as readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds useful content-level transparency by specifying exactly what data will be returned (installed MCPs, connection status, accounts, catalog tool counts). This goes beyond the annotations and gives the agent a concrete expectation of the output, warranting a 4.

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, tightly written sentence that front-loads the purpose ('Returns the current toolkit state') and enumerates the key details without any unnecessary words. Every phrase adds value, there is no fluff, and the structure is optimal for quick parsing.

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 read-only information tool with no parameters and no output schema, the description fully covers what the tool does and what it returns. It lists all categories of information, making the output predictable. There are no hidden surprises, and the description is sufficient for an agent to understand the tool's role without further elaboration.

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 description coverage is 100% (no properties). With no parameters to document, the baseline is 4. The description does not need to elaborate on parameter semantics since there are none, and it correctly focuses on the returned state.

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: it returns current toolkit state, listing specific types of information (installed MCPs, connection status, connected accounts, catalog tool counts). The verb 'returns' plus the resource 'toolkit state' is specific and distinguishes it from sibling tools like authenticate, connect, or marketplace which perform actions rather than read-only queries.

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 implicitly conveys when to use this tool: whenever you need to inspect the toolkit's state, connections, or the accounts/features exposed by MCPs. It does not explicitly mention alternatives or exclusions, but given the tool's self-explanatory nature and that there is no direct sibling alternative for this exact function, the context is clear enough. A 4 is appropriate—clear context without explicit when-not-to-use.

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