Procuradoria Geral do Estado RJ: Dívida Ativa

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

Annotations declare readOnlyHint=false and idempotentHint=true, but the description adds practical behavioral context: the token is non-expiring if configured as header and session-only if pasted. It implies mutating the server config, which is beyond annotations, but does not explicitly warn about side effects like overwriting existing config or security implications beyond saying 'permanent connection'.

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 but front-loaded with the main action and audience, then explains modes. The use of colons and bold-like notation (not actual markdown but clear) makes it scannable. It is slightly long but every sentence adds value, so no 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?

Given the tool's complexity (two auth methods), the description covers both user-facing and agent-facing actions. No output schema exists, so it doesn't describe return values, but it tells agents what to do with the link (get it by calling with no args). It could mention that the token is passed to the server and how the server will use it, but overall it is adequate for a tool with a single optional param.

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 one optional `token` parameter with no description. The description explains `{ token: "<jwt>" }` and the no-arg case, which adds meaning. However, it doesn't explain the token format beyond '<jwt>', nor does it clarify what happens if a token is provided in both config and call. Schema coverage is 0%, so description compensates but could be more precise about token requirements.

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: authenticate via browser login and token exchange, with two modes (permanent config header or session-only token). It distinguishes from siblings by explicitly addressing IDE agents and the authentication flow, though it doesn't name sibling 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?

Provides explicit usage scenarios: 'add it to this server's config as a header' for permanent vs 'paste it here for a session-only login', and instructs calling with or without args to get the link. Also mentions `token` param for session login. This goes beyond mere guidance to direct the agent on when to use each mode.

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. The description adds valuable behavioral context by explaining the conditional responses (authenticated:true with empty pending[] when all connected, or connect_url and per-install URLs when credentials missing). 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 concise, with two sentences that front-load the core purpose and then explain the conditional outputs. Every sentence adds value, with no padding or redundancy.

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 no output schema and no parameters, the description explains the return values well (e.g., authenticated, pending[], connect_url, per-install URLs). It does not cover error cases or mention that it does not trigger authentication, but the tool's simplicity and the provided conditions make it sufficiently 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 description does not need to add parameter semantics. Per the guidelines, a baseline of 4 is appropriate when there are no parameters to describe.

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: 'Returns connection status and URLs.' It specifies the output conditions for both connected and missing credential scenarios, which distinguishes it from sibling tools like authenticate (which presumably initiates authentication) by focusing on status checking.

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 (e.g., when you need to check connection status) but does not explicitly state when to use this tool versus alternatives like authenticate or show_version. There are no exclusions or comparisons to sibling tools, so guidance is only implied.

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?

It discloses key behavioral traits beyond annotations: invoke works without installation, returns a connect link when credentials are needed, returns a checkout/top-up link when the wallet is empty, and writes require workspace owner/admin. These details explain side effects, auth requirements, and retry behavior. No contradiction with the provided 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 long but information-dense and front-loaded with the core purpose and flow. Every sentence adds value, though the single-paragraph structure could be improved with bullets or section breaks for easier scanning.

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 complex 14-action tool with no output schema, the description covers the core flow, auth requirements, one-off vs permanent behavior, and the prompt library. However, it omits the resume action and several prompt/request parameters, and return-value behavior is only partially described.

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% schema description coverage, the description carries the semantic burden. It explains the central action enum thoroughly and clarifies tool_id, prompt_slug, and the prompt library parameters. It does not enumerate all 23 parameters, but it adds substantial meaning to the most important selector and workflow parameters.

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 marketplace as the official mcp.ai catalog and execution layer, with a specific core flow (search → describe → invoke) and distinct sub-actions (install, list_tools, prompt library). It distinguishes itself from siblings by positioning itself as the in-platform catalog/runner rather than a single-purpose tool 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 gives explicit when-to-use guidance: search discovers MCPs by intent, describe returns profiles so you pick the right tool_id, invoke runs one-off even when not installed, install is only for permanent toolkit additions, and request_mcp is for when nothing fits. It also says to prefer invoke for single/occasional use and lists list_tools as the way to see what is callable right now.

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 goes beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by explaining payment model (pague por consulta com crédito pré-pago), that it uses official sources with no platform credentials, no confidential data, and LGPD compliance. This adds valuable behavioral context about authentication and data handling that is not inferable from 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 dense paragraph but stays reasonably concise. It conveys the core purpose, payment model, data source, and legal note about LGPD in about 40 words. No redundant sentences, though some legal info (LGPD) might be secondary; it's still relevant for compliance. It is front-loaded with the key 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?

With 3 parameters and no output schema, the description should explain more about expected inputs and outputs. It explains the source, payment, and data privacy, but doesn't mention how to provide CPF/CNPJ/RENAVAM formats, whether all are required, or what the response looks like. Given the lack of parameter descriptions and output schema, this is a notable gap.

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% – the properties have no descriptions. The description provides no elaboration on the parameters (cpf, cnpj, renavam) beyond their names, which are self-explanatory but do not specify formats (e.g., with/without punctuation), which identifier to use, or if they are alternative or combined. The description does not compensate for the lack of schema documentation.

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 consulting 'Dívida Ativa' from the Rio de Janeiro State Attorney General's office. It specifies the action (consulta), the resource (Dívida Ativa), and the source (oficial). It is unmistakably distinct from the unrelated sibling tools (authenticate, connect, etc.), making its purpose 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 does not explicitly mention alternative tools or when to avoid using this one. However, it clearly sets context: it's for consulting official public records, implying it should be used when such data is needed. There is no exclusionary guidance, but the purpose is so specific that usage is implied. This is adequate but not 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=false, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context by instructing the agent to include the conversation array with recent messages for reproduction purposes. This goes beyond structured annotations, though it doesn't describe side effects like potential duplicate tickets or requiring authentication.

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: the first states the purpose, the second gives an explicit instruction on usage. Every word earns its place, no redundancy or 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?

For a bug-feedback tool with three simple parameters and no output schema, the description gives the core purpose and a key usage note. However, because parameter semantics are incomplete (context and message are unexplained) and there is no guidance on expected outcomes or reply format, it is only minimally 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?

The schema has 0% description coverage, so the description must compensate for all three parameters. It mentions the 'conversation' parameter and its purpose (aids reproduction) but does not explain 'message' (the required field) or 'context'. This leaves significant gaps in parameter understanding.

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 verb ('Report') with explicit resource types ('a bug, missing feature, or send feedback'), making the tool's purpose unmistakable. It naturally distinguishes itself from sibling tools like 'authenticate' or 'marketplace', which handle unrelated concerns.

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 clearly implies when to use the tool: whenever a user reports a bug, requests a feature, or provides feedback. It does not explicitly state when not to use it or name alternatives, but no sibling tool serves a similar purpose, so exclusionary guidance is 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?

The description matches the annotations (readOnly, idempotent, non-destructive). It does not mention any side effects, but none are expected for a version query. It adds no extra behavioral details, but the annotations already cover the safety profile.

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, clear sentence with no unnecessary words. It conveys the essential information immediately.

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, the description is complete. It provides sufficient context about what is returned (platform and adapter versions) without needing an output schema. No additional details are missing.

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 no parameters, so nothing needs to be explained. The empty schema is consistent with the description, and no additional parameter semantics 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 clearly states the tool's function: showing the current MCP platform and adapter versions. It is specific and distinguishes itself from sibling tools like authenticate or connect, which perform different actions.

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 usage is self-evident: call this tool to retrieve version information. There are no alternative tools for this purpose, and no complex conditions apply, so the description sufficiently guides when to use it.

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. The description adds meaningful context beyond those flags by specifying what the state snapshot includes: installed MCPs, connection status, connected accounts per MCP, and catalog tool counts. It gives a clearer sense of behavioral scope without requiring speculation.

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 well-structured sentence that information all relevant aspects in a compact, front-loaded way. No filler, repetition, or extraneous content is present.

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 tool, this description is sufficient. It explains the content of the returned information, no output schema or nested object require additional elaboration, and the annotations cover behavior. An agent can confidently select and invoke this tool based solely on this description.

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 no required arguments, so there is no semantic gap to fill. The schema is empty and complete; the description correctly focuses on describing the output rather than parameter behavior.

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 verb ('Returns') and specifies the exact resource ('current toolkit state') plus the categories of information it conveys (installed MCPs, connection status, connected accounts, catalog tool counts). This distinguishes it from sibling tools like show_version or authenticate by defining a distinct status/inspection responsibility.

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 context is implicitly clear: call to inspect toolkit state, installed MCPs, connection status, and accounts. However, there is no explicit guidance about when to use this tool versus siblings such as connect, marketplace, or show_version, so the agent must infer this from the description.

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