Tesouro Nacional: Capacidade de Pagamento (CAPAG)

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

Beyond the annotations, it reveals that no-arg calls return an auth link, config-header login is permanent/non-expiring, and token-based login is session-only. This adds meaningful context without contradicting the idempotentHint or other 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, covering the audience, the login mechanism, and two invocation paths in just a few sentences. It is slightly dense and could be reordered, but every sentence contributes.

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 low-complexity tool with a single optional parameter and no output schema, the description fully covers the both permanent and session-based paths, including the exact token format and the no-arg behavior. The agent can safely and correctly invoke this tool with or without a token.

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 undocumented optional token string, and the description fully compensates by identifying it as a JWT copied from the browser, giving the exact { token: "<jwt>" } invocation shape, and explaining when to omit it. Parameter semantics are unambiguous despite 0% schema coverage.

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 this tool authenticates for the MCP.AI server and describes the browser-token flow, giving a specific action and resource. It does not explicitly distinguish itself from the sibling connect tool, which creates minor ambiguity.

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 concrete usage options: use a config Authorization header for a permanent connection, pass a token for session-only login, or call with no args to get an authentication link. It lacks an explicit 'when not to use this tool' or direct alternative recommendations.

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, so the agent knows this is a safe read operation. The description adds value by explaining the response structure (authenticated, pending, connect_url), which is useful context beyond the annotations. However, it does not disclose any potential caveats (e.g., what happens on partial connection), but the baseline is adequate.

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, both front-loaded with the key purpose, and every sentence provides valuable information. There is 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?

Given the tool's simplicity (zero parameters, no output schema), the description is quite complete. It covers the two primary states (connected and missing credentials) and mentions per-install URLs. It could elaborate on partial connection states, but given the minimal complexity, 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?

The tool has zero parameters, so the schema is trivially complete (100% coverage). The description adds meaning by explaining what the output will be, effectively compensating for the lack of parameters. The baseline for zero params is 4, and the description provides clear 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's purpose: it returns connection status and URLs, with explicit details about the response states (authenticated:true with empty pending[] when connected, connect_url when credentials are missing). This is specific and distinguishes it from siblings like 'authenticate' and '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 when to use this tool: to check connection status or obtain connect URLs when credentials are missing. It does not explicitly mention alternatives or when not to use it, but the context is clear enough given the zero-parameter nature and sibling tools.

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 (openWorldHint=true, readOnlyHint=false), so the description carries the burden, and it mostly delivers: it discloses the 'invoke works even when MCP is NOT installed' one-off behavior, auth requirements (connect links), payment gates (checkout links), permission levels for writes, and side-effect behavior of install/uninstall/subscribe. Minor deduction because some important behaviors are buried mid-sentence and the ungrammatical 'pontualmente (one-off)' confuses rather than clarifies.

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?

This is a single 600+ word run-on paragraph with no paragraph breaks, bullet points, or formatting to aid scanning. It contains redundant digressions like 'consulta um CPF' (an example in Portuguese) and 'KEY:' emphasis is not backed by structural highlighting. Some critical information (the 3-step workflow) is buried mid-sentence. For an LLM agent, this is borderline unusable for quickly identifying the relevant action.

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 this complex (14 actions, 23 params, no output schema, no annotations beyond two booleans), the description does an impressive job covering: the search/describe/invoke core flow, the installed vs one-off distinction, auth and payment handoffs, ownership permissions, the prompt library sub-feature, and the distinction between installed_in_toolkit vs installed_in_workspace. However, given the sheer surface area, it would benefit from specifying response shapes and which fields apply to which 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 0% schema coverage and 23 parameters, the description absolutely must explain the parameters, and it does cover the action enum (search, describe, install, invoke, subscribe, etc.) and mentions tool_id selection. However, the description does not map specific parameters like prompt_vars, conversation, cancel_reason to their semantics, nor explain what the reserved default values mean (e.g., arguments='{}', conversation='[]'). An agent calling this tool would still be unsure what format prompt_vars or request_details expect.

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 establishes this as the mcp.ai marketplace catalog and tool runner, with a specific verb+resource: 'find an MCP that does X' and 'invoke RUNS that tool.' It distinguishes the core workflow (search → describe → invoke) and differentiates from siblings by contrasting with `install` for permanent additions. However, the single-purpose clarity is diluted by covering 14+ actions including a separate 'PROMPT LIBRARY' feature, making the overall purpose slightly scattershot.

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?

Excellent explicit when/when-not guidance: 'Use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use' and 'list_tools lists what is callable right now.' It explains conditions for auth (connect link) and payment (checkout link) with a retry protocol ('the user opens it, then you retry'). Also clarifies that writes require workspace owner/admin and that search/describe flags installed_in_toolkit vs installed_in_workspace.

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 (readOnlyHint false, destructiveHint false, idempotentHint true) already disclose the safety profile. The description adds that the conversation array is needed for reproduction, which is a minor behavioral note. No contradiction; but no rich behavioral context 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 two concise sentences with zero filler. It front-loads the core purpose and then gives a specific instruction about the conversation parameter. Every sentence 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?

Given the tool has 3 parameters (1 required), no output schema, and no nested objects, the description is insufficient. It omits the purpose of 'context', does not indicate which parameter is required, and does not explain what happens after reporting. The lack of schema descriptions makes this gap significant.

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 'conversation' parameter ('Include the conversation array with recent messages for reproduction') but does not explain 'message' (required) or 'context'. The description provides partial value but leaves key parameters 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 clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' It uses a specific verb (report) with a clear object, and the sibling tools (authenticate, connect, marketplace, etc.) are all distinct functional areas, so there is no ambiguity or overlap.

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 you have a bug/feedback) but does not explicitly contrast with alternatives or provide exclusions. It does not mention when not to use it, but given the clear distinctiveness from siblings, this is acceptable yet minimal.

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, and destructiveHint=false, so the safety profile is clear. The description adds that the version shown is 'current,' implying a live read operation, which is useful and consistent with 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, front-loaded sentence that contains zero filler. Every word contributes to the meaning, and it is appropriately sized for the tool's simplicity.

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 such a low-complexity tool with no input schema parameters, no output schema, and strong annotations, the two-part description fully communicates the tool's function. No additional context is necessary.

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, and schema coverage is 100% (trivially). The description does not need to explain any parameters; the baseline of 4 is appropriate for a no-parameter 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 uses a specific verb ('Show') plus a precise resource ('current MCP platform and adapter versions'), clearly distinguishing this from siblings like authenticate and connect. It unambiguously states what the tool does.

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 explicit guidance on when to use this tool versus alternatives such as toolkit_info. The context is simple, and usage is implied by the name and description, but there is no stated exclusion or alternative discussion.

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 significant behavioral traits beyond annotations: requiring prepaid credit, not needing platform credentials, data being public/non-confidential, and LGPD responsibilities. This provides valuable context about costs, authentication, and legal handling that annotations alone do not convey.

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 three sentences and about 50 words, efficiently covering purpose, access, cost, and legal context. There is slight redundancy between 'fonte oficial' and 'fontes e órgãos oficiais', but overall it is well-structured 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?

Given the simple query tool, the description provides rich context but lacks parameter semantics and does not specify output or further usage caveats. It compensates for the absence of an output schema with cost and confidentiality details, but the parameter gap keeps it from being fully 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?

Schema description coverage is 0%, and the description does not explain the parameters 'uf' and 'municipio'. While the parameter names are self-explanatory, the description fails to add any explicit meaning or relationship to the query, leaving the agent to infer the required 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 clearly states this is a query tool for CAPAG (Payment Capacity) from the official National Treasury source. The verb 'consulta' and resource 'Tesouro Nacional: Capacidade de Pagamento (CAPAG)' specify exactly what the tool does, and it is distinct from the generic 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?

The description implies usage context (querying official Brazilian data) and mentions access conditions (no platform credentials, prepaid credit), but it does not explicitly state when to use this vs alternatives. There is no exclusionary guidance, but the intended use case is clear enough from the 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral detail by specifying what the returned state contains, without contradicting 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?

The description is a single, well-structured sentence that leads with the action and packs all key content into a compact list. No words are wasted.

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 strong annotations, the description provides sufficient detail about the return content. It could be slightly more complete by noting the output format or how this complements sibling tools, but those are not critical 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?

The tool has zero parameters, so the baseline of 4 applies; there is no parameter information that needs to be supplied by the description.

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 states a specific verb ('Returns') and resource ('current toolkit state'), then enumerates exactly what that state includes: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly distinguishes it from sibling tools like connect, authenticate, and 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 for inspecting current toolkit state, but it provides no explicit when-to-use guidance or mentions alternatives. A clear context is present, but there are no exclusions or decision rules relative to sibling tools.

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