Banco Central do Brasil (BCB): Valores a Receber

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

Adds context beyond annotations by describing the two login modes (permanent vs session) and the browser flow. However, it does not mention error handling or what happens on invalid token, though idempotentHint suggests repeat calls are safe. The description covers essential side effects without being exhaustive.

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?

Description is compact yet information-dense. Leads with purpose, then clearly delineates two methods ('Best:' and 'Or'). No fluff, every sentence serves the user.

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 authentication paths, optional param, no output schema), the description fully explains both modes, the user interaction (browser login), and how to invoke with or without token. Ample for correct 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?

Schema has 0% coverage for the 'token' parameter, but the description compensates well: it explains the token is a JWT used for session login, and gives the exact call format. It lacks details on token format validation or expiration, but is sufficient for usage.

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?

Clearly states the tool's purpose: authentication for MCP.AI IDE agents, with explicit instructions for browser login and token usage. It distinguishes from siblings like 'connect' and 'marketplace', 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?

Provides explicit when-to-use guidance: 'Best: add it to this server's config as a header' for permanent login, or 'paste it here for a session-only login'. Also instructs exact call patterns: with token after user pastes, or no args to get link. No alternatives are needed as no sibling performs authentication.

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, openWorldHint, idempotentHint, and destructiveHint, but the description goes well beyond that by disclosing payment requirements (prepaid credit), authentication (no platform credentials), data classification (not confidential), and legal responsibilities (LGPD). This gives the agent critical operational and compliance information not captured in 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 reasonably concise and front-loaded with the core purpose, followed by payment and legal details. While the LGPD clause adds length, it is relevant to data handling. The structure is clear, with each sentence adding distinct information, but it could be slightly tightened without losing essential context.

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 schema and lack of output schema, the description provides useful context about the official source, cost, and legal obligations, but it omits guidance on how to combine parameters (e.g., CPF vs CNPJ) and what type of response to expect. The tool is not overly complex, but the missing parameter details and return value information leave the description incomplete for smooth 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?

The input schema has four parameters (cpf, cnpj, data_nascimento, data_abertura_empresa) with 0% description coverage, and the tool description provides no explanation of these parameters. The description does not compensate for the lack of schema descriptions, leaving the agent to infer parameter usage solely from their names. This is a significant gap in guidance.

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 a query tool for the Banco Central do Brasil's 'Valores a Receber' program, using the specific verb 'consulta' and specifying the official source. It distinguishes itself from the platform-level sibling tools (authenticate, connect, etc.) by focusing on a concrete Brazilian government data service.

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 usage context: it is a paid consultation using prepaid credits, requiring no platform credentials, and it queries official Brazilian sources. It does not explicitly mention when not to use it or name alternatives, but the context is clear enough that the agent can decide to use it for fetching BCB 'Valores a Receber' data. No exclusions are needed given that sibling tools are unrelated.

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 mark it read-only and idempotent; the description adds valuable detail about response fields (authenticated, pending[], connect_url) and conditions, going 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 concise sentences: the first states the primary purpose, the second explains conditional behavior. No fluff; every word adds value.

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 stateless, parameterless tool, the description covers return values and key edge cases (credentials missing). It lacks minor details like response format or error codes but is largely complete given low complexity.

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?

There are zero parameters, and schema coverage is 100% (vacuously). Per rubric, baseline is 4. No additional parameter info 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 clearly states the tool 'Returns connection status and URLs' with specific behavior for connected and missing-credential cases, distinguishing it from siblings like '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?

Usage is implied through the description of scenarios (all connected vs missing credentials), but no explicit alternatives or when-not-to-use guidance is given compared to siblings.

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 only provide readOnlyHint=false and openWorldHint=true, so they do not fully disclose the safety profile. The description compensates by explicitly stating that writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin. It also discloses key behaviors: invoke works for non-installed MCPs, runs one-off without bloating the toolkit, and returns connect/checkout links when credentials or payment are needed. 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 a dense single paragraph but is well structured: core identity, core flow, KEY invoke behavior, install distinctions, permissions, and prompt library are all covered in sequence. It is long, but the tool has a very large surface area and every sentence contributes operational value. Some minor front-loading improvements are possible, but it is not padded.

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, multi-mode tool with no output schema, this description is unusually complete. It covers the main pipeline, the invoke vs install tradeoff, permission requirements, connect/checkout behavior, installed flags, prompt library features, and admin write restrictions. It does not enumerate exact return shapes for each action, but given the breadth of the tool, the contextual package 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?

Schema description coverage is 0% and there are 23 parameters, so the description carries a heavy burden for parameter semantics. It does narratively explain the action enum values and connects them to relevant parameters (mcp_id, tool_id, arguments, prompt_vars, prompt_slug, prompt_body). However, many parameters such as limit, query, immediate, tier_slug, conversation, cancel_reason, request_name, and prompt_targets are not individually explained, leaving real gaps.

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 by identifying the tool as 'the official mcp.ai marketplace' and clearly states that it is both a catalog of MCPs/tools and the way to run them. It names the core actions and example user intents it serves. It is a multi-action dispatcher rather than a single verb+resource, but the purpose is unambiguous and the internal modes are well distinguished.

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 an explicit core flow: search → describe → invoke, and explains when each step is appropriate. It directly contrasts invoke and install: 'prefer invoke for a single/occasional use' versus 'Use install only to make an MCP PERMANENT'. It also clarifies when to use list_tools, subscribe/cancel, report_bug, request_mcp, and the prompt library actions, making this excellent usage 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 provide readOnly=false, destructive=false, idempotent=true, which are not contradicted. However, description does not disclose side effects (e.g., sending a ticket) or response behavior beyond the parameter hint.

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 with no redundant information, clearly actionable and structured.

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 reporting tool, description adequately covers essential usage. No output schema, but return values are likely trivial (e.g., success indicator) and not essential for 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 shows three parameters: message (required), context (default), conversation (default). Description only elaborates on conversation, leaving message and context undefined. Coverage is below 50%, requiring the model to infer their roles.

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?

Description clearly states the tool's purpose: reporting bugs, missing features, or feedback. Distinct from sibling tools like authenticate or connect.

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?

Implies when to use (for reporting issues) and gives specific instruction to include conversation array for reproduction. Lacks explicit alternatives or exclusions but sufficient for 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 indicate read-only, idempotent, and non-destructive behavior. The description adds no extra context about side effects or limitations, relying on the annotations. This meets the lower bar but does not go beyond.

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 redundant words. It is efficiently structured and directly conveys the tool's 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?

For a simple version-query tool with no parameters or output schema, the description is complete. It fully communicates what the tool does without needing further context.

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 provides no additional parameter information, but none 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 clearly states the tool's function: showing MCP platform and adapter versions. It is specific and distinct from sibling tools, which handle authentication, data querying, connectivity, marketplace, bug reporting, and 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 when to use (when needing version information) but does not explicitly mention alternatives or exclusions. Since no sibling tool serves a similar purpose, the guidance is adequate but not exhaustive.

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 establish this as a safe, read-only, idempotent operation. The description adds meaningful value by detailing exactly what state is surfaced (MCPs, connection status, accounts, catalog tool counts), going beyond what annotations state. No contradictions with the readOnlyHint=true flag. Minor gap: no mention of errors or empty-state behavior.

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 immediately names the resource ('toolkit state') followed by a colon-delimited list of contents. Zero waste — every word contributes to the operational 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?

For a no-parameter, read-only getter with strong annotations and a detailed return-content description, the documentation is largely complete. The only minor additions could be error conditions or a note about instance-wide state, but these are not necessary for a simple tool of this nature.

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, which sets a baseline of 4 under the rubric. The description adds no parameter info, but since there are no parameters to document, the description is not expected to compensate for any schema gaps.

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') plus a concrete resource ('the current toolkit state') and elaborates with a detailed list of what that state includes: installed MCPs, connection status, connected accounts, and catalog tool counts. This level of specificity clearly separates it from sibling tools like `show_version` and `connect`.

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 implied rather than explicit — the reader can infer 'use this when you need toolkit state info' but there is no explicit 'when to use vs alternatives' guidance. For instance, it doesn't clarify when to use this versus `show_version` or `authenticate`, and no exclusions are provided.

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