Procuradoria Geral do Estado SP: Dívida Ativa

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

The description adds valuable context beyond annotations: it explains the two authentication modes (permanent via config vs session-only), the fact that the config method is 'permanent, non-expiring', and that calling with no args returns a link. This goes beyond the simple idempotentHint and clarifies the side effects of each call method.

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, fitting all necessary information into three sentences. It is somewhat run-on but still readable. It front-loads the purpose and then explains the two invocation modes. It earns its place without excessive verbosity.

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 complete. It covers both practical use cases (permanent and session-based), explains the dependency on browser login, and tells the agent how to call the tool. It could have mentioned potential errors or rate limits, but these are less relevant for an auth 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 only says 'token' is a string with no description. The description fully compensates by explaining that the token is a JWT to be passed after the user pastes it, and that omitting it triggers a link generation. This adds crucial meaning beyond the bare schema.

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 MCP.AI for IDE agents. It uses a specific verb ('log in') and resource ('MCP.AI'), and explains the overall flow. It distinguishes itself from siblings by focusing exclusively on authentication, setting the session vs. permanent token choice.

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 when-to-use guidance: call with no args to get the link, or pass the token after the user pastes it. It also mentions the alternative of adding the token to the server's config for a permanent connection, which is a form of alternative configuration. However, it doesn't state when NOT to use this tool or directly contrast with sibling tools like 'connect'.

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, destructiveHint=false, covering the safety profile. The description adds valuable context: it explains the conditional behavior based on connection state and what fields are returned (pending[], connect_url, per-install URLs). This goes beyond the annotations and gives the agent a mental model of the response shape.

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 extremely concise: two sentences that clearly state the tool's output and the two possible conditions. Every sentence earns its place, with no fluff or redundancy. It is front-loaded with the primary purpose and then elaborates on the conditional behavior.

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 0 parameters and no output schema, the description is fairly complete. It explains the primary return states and the fields involved. However, it could briefly mention the exact structure of the response (though not required) or clarify what 'per-install URLs' are, but given the tool's simplicity and the strong annotations, this is 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?

The tool has 0 parameters, so the schema provides no parameter information. The description doesn't need to describe parameters, but it adds semantic value by explaining the output structure and conditional fields, which helps the agent interpret the result. Since there are no params, a baseline of 4 is appropriate for adding meaningful behavioral semantics.

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, distinguishing it from siblings like 'authenticate' (which presumably initiates authentication) and 'marketplace' (which likely lists available tools). It explicitly mentions key outputs like authenticated:true and connect_url, giving a specific purpose with resource and behavior.

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 when to use it: to check if all providers are connected. It explains the two possible outcomes (authenticated:true with empty pending[], or missing credentials with connect_url). However, it doesn't explicitly say when not to use it or name alternative tools, but the purpose is clear enough for basic selection.

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 behavior: invoke runs uninstalled MCPs one-off without bloating the toolkit, missing credentials produce a connect link, empty wallet produces a checkout/top-up link, and writes require workspace owner/admin. This adds substantial behavioral context that annotations do not provide.

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 earns its place: purpose, core flow, key behavioral caveats, install-vs-invoke guidance, auth/billing handling, and the prompt-library subdomain. It is front-loaded with the most important information and is appropriately sized for a complex multi-action 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?

For a 23-parameter, 14-action tool with no output schema, the description covers the main workflows, permission requirements, billing/auth failure modes, installed-vs-one-off behavior, and prompt-library operations. It even describes key return behaviors (profile contents, connect/checkout links, prompt text). This is comprehensive enough for an agent to select and invoke the correct action.

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 must compensate. It explains the action enum values, the mcp_id/tool_id/arguments flow, and the prompt_* parameters at a high level. However, several parameters (limit, query, immediate, tier_slug, conversation, cancel_reason/comment, request_* fields) are not explicitly described, though their names are mostly self-explanatory.

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 tool as the mcp.ai marketplace: an in-platform catalog of MCPs/tools and the mechanism to run them. It provides a concrete core flow (search → describe → invoke) and distinguishes the prompt-library subdomain, making the tool's purpose unmistakable and distinct from siblings.

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 guidance on when to use invoke vs install ('prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT'), explains which actions handle billing, bug reports, and new MCP requests, and notes the auth/billing retry flow. This is strong when-to-use and 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.

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

Annotations clearly mark this as a read-only, idempotent, non-destructive operation. The description adds meaningful context on billing, credentials (no platform credentials needed, pre-paid credit per query), data governance (LGPD compliance, user is data controller), and the nature of the data (public, non-confidential). This enriches the agent's understanding of the invocation context. A slight deduction because it doesn't mention rate limits, authentication details, or what the exact response contains, but overall it contributes good value.

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 paragraph covering the key points: source, official nature, payment method, data governance, and LGPD compliance. It is slightly dense with legal text but remains focused. It could be more concise by removing redundancies, but it is not bloated.

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 moderate complexity and the absence of an output schema, the description provides good contextual completeness by covering authentication, payment, data scope, and legal responsibilities. It lacks information about response format or error cases, but for a simple query tool with rich annotations, this is sufficient.

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%, meaning the schema provides no descriptions. However, the parameter names (ie, cda, cpf, cnpj, renavam, cnpj_base) are self-explanatory for a Brazilian tax query tool. The description does not add semantic meaning beyond the names, but in this case the names are widely understood. Since no parameters are required, the agent can make a selection. A score of 4 is given because the description, combined with conventional schemas, allows confident invocation, though explicit documentation would have been better.

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 names the tool as 'PGE SP: Dívida Ativa, consulta em fonte oficial', which clearly identifies the resource (Dívida Ativa) and the action (consulta, 'query'). However, it is phrased more like a title and does not use a direct verb like 'Retrieve' or 'Search', and it does not distinguish from siblings besides implying a source. It is adequate but not specific enough to clearly separate from other potential Dívida Ativa tools.

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 mentions the source is official and that no platform credentials are needed, implying usage. However, there is no explicit guidance on when to use this tool versus alternatives (e.g., other state agencies, related queries), and no exclusions or when-not-to-use instructions. It is not misleading, but it fails to guide the agent on selection 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 cover safety (idempotentHint=true, destructiveHint=false), and the description adds the behavioral context that the conversation array aids reproduction. However, it does not describe what happens after submission, authentication needs, or any side effects 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?

Two sentences: the first front-loads the purpose, the second gives a concrete usage guideline. No filler or redundant content.

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 three parameters and no output schema, the description covers the core purpose and two parameter meanings. The 'context' parameter is a notable gap, but the overall tool behavior is adequately conveyed for basic 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?

Schema description coverage is 0%, so the description must compensate. It explains the 'message' parameter (the bug/feedback text) and 'conversation' (for reproduction), but the 'context' parameter remains entirely unexplained. Partial compensation 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 clearly states the tool's action ('Report') and its targets ('a bug, missing feature, or send feedback'). This is specific and distinct from the unrelated sibling tools such as authenticate 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 instruction to include the conversation array with recent messages for reproduction provides clear usage context. While no explicit 'when not to use' or alternatives are given, the sibling tools are unrelated, so the implied usage is sufficient.

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, and the description adds the specific output content ('MCP platform and adapter versions'). This is consistent and provides additional context beyond the annotations, though no detail is given about the exact return format.

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, direct sentence fully conveys the tool's purpose with no filler or repetition. It is appropriately sized and 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?

For a no-parameter, read-only version query with strong annotations and no output schema, the description is complete. It tells the agent what the tool reports (platform and adapter versions) and the safety profile is covered by 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 is 4; no parameter documentation is needed. The description adds no parameter semantics, but none are 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 uses a specific verb ('Show') and resource ('MCP platform and adapter versions'), clearly stating what the tool does. It is distinct from siblings like authenticate or toolkit_info.

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 when version information is needed but does not explicitly contrast with alternatives or state when not to use it. For a simple no-arg utility, the usage context is reasonably clear but not elaborated.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context by enumerating exactly what aspects of state are exposed (installed MCPs, connection status, accounts, catalog counts), going beyond what annotations alone convey. It does not contradict any 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 entire description is a single, well-structured sentence that front-loads the purpose ('Returns the current toolkit state') and follows with a colon-delimited list of components. No words are wasted, and the structure makes it easy to parse the tool's output capabilities at a glance.

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 informational tool, the description fully covers the necessary information: what the tool does and what it returns, with a clear breakdown of the data included. There is no output schema, but none is needed given the simplicity. The description is completely sufficient for an agent to decide whether to call 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?

The tool has zero parameters, so the baseline of 4 applies. The description correctly adds no parameter-related information, which is entirely appropriate since there is nothing to explain. Schema coverage is 100% (vacuously), and no compensation is needed.

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 clearly defines the resource ('current toolkit state') followed by a list of contents: installed MCPs, connection status, accounts, and catalog tool counts. It distinctly differentiates itself from sibling tools like 'show_version' by focusing on the entire state rather than just version info.

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 clear usage context—when an agent needs to understand the toolkit's current state—by directly stating what information is returned. It does not explicitly provide when-not-to-use guidance or mention alternatives, but for a simple state-query tool, the context is sufficiently clear.

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