Capivara: Investigação Cadastral

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

Annotations provide idempotentHint=true, readOnlyHint=false, and destructiveHint=false, and the description adds useful context beyond these: the config-header path yields a permanent, non-expiring connection, while the pasted-token path is session-only. It also discloses that no-args returns the login link. There is no contradiction 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?

The description is a single dense paragraph but contains no filler; it front-loads the purpose and packs in audience, browser flow, permanent vs session options, and call shapes. It could be more scannable with bullets or separate sentences, but it remains concise and information-dense.

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 one optional parameter, no output schema, and no auth-related siblings, the description covers the core flows and expected outcomes: getting a login link or performing a session login. It does not specify the exact return value for the token-present case or failure handling, but the essential decision guidance for an agent is fully present.

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 exposes only an optional, undocumented string parameter `token` (0% description coverage). The description compensates fully by explaining that the token should be a JWT/access token, how to pass it in the call, and that omitting it triggers the link-generation flow. This transforms an opaque schema field into an actionable parameter.

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: authenticate with MCP.AI by either returning a login link when called with no arguments or accepting a pasted JWT/access token. It identifies the resource (MCP.AI server) and the action (log in / authenticate), and the sibling list contains no other auth-related tool, so there is no 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 explicit usage paths: call with no args to get the login link, or call with { token: "<jwt>" } after the user pastes it. It also distinguishes the recommended permanent config-header approach from the session-only token-paste approach. It does not mention alternative tools explicitly, but no sibling tool serves an auth purpose, so the guidance is adequate.

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 (readOnly, idempotent, non-destructive), the description discloses pricing, response time, response format (summary + .md file), token size limitations, the fact that data may be incomplete/outdated, and LGPD compliance. It clearly states the extra cost and authorization requirement for SCR, providing full transparency about how the tool behaves.

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 quite long but well-organized: first the purpose, then details for PF/PJ, then pricing/levels, timing, SCR requirements, response format, and legal caveats. Every sentence adds essential information, though a bit dense. It is front-loaded with the core purpose and ends with necessary caveats.

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 6 parameters and no output schema, the description covers all necessary operational aspects: input selection, level choices, costs, time expectations, response structure (with reference to arquivo_ler), authorization handling, and data reliability caveats. It leaves no obvious gaps for an agent to successfully invoke and interpret the 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 provides only parameter names and types, with no descriptions (coverage 0%). The description compensates fully: it explains that cpf_or_cnpj selects person/company, that nivel determines price and scope, that formato=resumo is default (summary + .md) while completo is for programmatic use, and that autorizacao_titular_scr gates restricted data. This is far beyond what the schema offers.

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: a 360º background check ('Raio-X cadastral') for either a person (by CPF) or company (by CNPJ), consolidating data into a report. It distinguishes itself from siblings like 'capivara_resolver' and 'capivara_registrar_consentimento' by being a comprehensive, multi-source dossier 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?

It gives explicit usage instructions: provide either cpf or cnpj, choose a nivel (with pricing), and note that SCR data requires authorization and is charged extra. It advises informing users about long wait times for the 'avancado' level and mentions that 'formato=completo' is for programmatic use. It does not explicitly name alternative tools, but the context 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 indicate a non-read-only, non-idempotent, non-destructive operation. The description adds valuable context: it states the registration is auditable, records who declared and when (in the audit log), and notes it's free. This goes beyond the annotations, though it doesn't elaborate on potential side effects like overwriting or failure modes.

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 front-loaded with the core function, then gives usage instructions, then audit details and cost. It's three sentences, each with a distinct purpose, and no filler. Slightly longer than minimalist but appropriate for the complexity.

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 6 parameters, 1 enum, and no output schema, the description covers the main behavioral aspects: what is registered, when to use it, and the audit trail. It also references a related external parameter (`autorizacao_titular_scr=true`) for re-running the dossiê. It's reasonably complete for a simple consent registration tool, though it doesn't describe return values or error cases.

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 provide parameter meaning. It explains the core parameters 'finalidade' and 'base_legal' (explicitly named), and 'autorizacao_titular' via the declaration phrase. However, it does not mention 'cpf', 'cnpj', or 'observacao', which remain unexplained. It provides partial meaning but not full 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 the tool's purpose: to register, in an auditable manner (LGPD), the purpose and legal basis of an investigation, plus a user declaration of authorization for confidential data. It explicitly names the resource (consent registration) and differentiates from siblings by referencing `capivara_dossie` and the conditional use case (when using protected data).

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: 'Chame ANTES do `capivara_dossie` quando for usar dados sob sigilo' and instructs to re-run the dossiê with `autorizacao_titular_scr=true` afterward. It also notes it's 'quando aplicável' and mentions it's free, providing clear context and alternatives.

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 valuable behavioral context: the CPF is only confirmed when corroborated across multiple companies, otherwise candidates are returned. It also warns about incomplete data due to LGPD and abstracts the source. This goes beyond annotations to clarify expected output and limitations.

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 moderately long but well-structured, starting with a clear layer designation and then explaining the process, usage, parameters, and caveats in a logical flow. Each sentence adds meaningful information, though it could be slightly more concise without losing key details.

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 output schema, the description covers the return values (normalized profile or candidates), the confirmation logic, the follow-up option, and data caveats. It also addresses prerequisites (free text) and optional shortcuts (cnpj). Given the tool's complexity and missing schema, the description is sufficiently complete to guide an agent.

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 all parameters. It does explain texto, cnpj, and seguir_dossie with purpose and usage. However, it entirely omits the 'nivel' parameter (basico/medio/avancado), leaving the agent without guidance on that important option. This is a significant gap for a tool with no schema descriptions.

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: identity discovery from free text, returning a normalized profile. It specifies the exact input (free text) and output (profile with name, CPF, companies, etc.), and distinguishes itself from the sibling tool capivara_dossie by explicitly stating when to use it (before capivara_dossie when CPF is unknown).

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 guidance: use before capivara_dossie when CPF is unknown, provide texto with as much detail as possible, optional cnpj as a shortcut, and set seguir_dossie to true for a follow-up. This gives clear when-to-use and how-to-use instructions, and differentiates from the sibling.

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 safety profile is covered. The description adds valuable behavioral context by detailing the return values in different states (authenticated:true and empty pending[] vs connect_url and per-install URLs), which is beyond annotation scope.

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 tightly written sentences cover all necessary information without redundancy. The description is front-loaded with the core purpose and immediately provides conditional outcomes.

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 read-only status tool with no parameters and no output schema, the description is nearly complete. It explains the two meaningful states (connected vs missing credentials) and what URLs are returned. It doesn't mention potential errors or pagination, but these are not needed given the tool's simplicity.

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 100% covered. The description adds no parameter-specific info, but the baseline for zero-param tools is 4, and there is nothing to improve upon.

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, and distinguishes its purpose from siblings like authenticate by focusing on status retrieval rather than action. It also specifies the two possible outcomes (all connected vs missing credentials), making 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: it's for checking connection status and getting URLs when credentials are missing. However, it does not explicitly state when to choose this over siblings like authenticate or toolkit_info, nor does it provide exclusion criteria. The context is clear but not fully 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?

Annotations only provide readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds significant behavioral context: invoke runs one-off without installing, install makes permanent, writes require workspace owner/admin, and invoke returns connect/checkout links when credentials or payment are needed. It doesn't contradict annotations. Slight deduction because it doesn't explicitly state that invoke is non-idempotent or that some actions may have side effects beyond what's implied, but the coverage is strong.

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 with many clauses and parentheticals. It's information-rich but not well-structured; it could benefit from bullet points or clearer separation of the marketplace flow vs prompt library. It's not overly long for the complexity, but the lack of structure makes it harder to parse. Front-loading is decent (starts with purpose), but the run-on style hurts readability.

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 (23 params, 14 actions, no output schema), the description covers the core flow, the key distinction between invoke and install, auth requirements, and the prompt library. It doesn't explain return values (no output schema) but that's not required. It could mention error handling or the exact behavior of 'resume' action, but overall it's quite complete for such a multi-purpose 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?

Schema description coverage is 0%, so the description must compensate. It explains the key parameters (action, mcp_id, tool_id, arguments, prompt_* fields) in context of the flow, and mentions the action enum values explicitly. However, it doesn't detail every parameter (e.g., limit, immediate, tier_slug, conversation, report_context) and their exact semantics, but given the 23 parameters, the description covers the most important ones and the action-driven behavior. A 4 is appropriate because it adds substantial 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 this is the official mcp.ai marketplace catalog and execution platform, covering both discovery and running of MCPs. It explicitly distinguishes from siblings by naming the core flow (search → describe → invoke) and the prompt library sub-feature, which differentiates it from other 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?

The description provides explicit guidance on when to use invoke vs install, when to use search vs describe, and when to use the prompt library functions. It even gives example queries ('find an MCP that does X', 'consulta um CPF') and explains the retry flow after connect/checkout links. This is exemplary 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 already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds the instruction to include conversation for reproduction, but doesn't disclose what happens when the tool is called (e.g., where the report goes, whether it's persisted). It doesn't contradict annotations, but adds little beyond 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?

Two concise sentences, no redundancy, clear instruction.

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, the description gives the basic purpose and one key usage detail. However, it doesn't specify what happens after reporting or any prerequisites. With no output schema, it might be sufficient, but it's not fully complete. I'd say 3.

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 explicitly mentions the 'conversation' parameter and implies the 'message' via 'Report a bug...' but doesn't explain the 'context' parameter at all. Only partial compensation.

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 resource (bug/feedback) and is distinct from sibling tools, which appear to be unrelated (e.g., connect, marketplace, show_version). No 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 a hint about usage by instructing to include the conversation array for reproduction, but it doesn't explicitly state when to use this tool vs alternatives. Since siblings are unrelated, there's no conflict, but no explicit when/when-not guidance is provided.

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 agent knows this is a safe, non-destructive read. The description adds minimal extra behavioral context beyond stating what it shows; it doesn't mention any side effects (likely none) or output specifics, but given the annotations, a 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 sentence that is concise and front-loaded with the action and resource. Every word earns its place; there is zero 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?

This is a simple read-only tool with no parameters, rich annotations, and a clear description. The context is complete for the agent to understand its purpose and safety. The only minor gap is the lack of guidance on alternative tools, but given the simplicity, this is not a significant omission.

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%, so there is no need for parameter explanations. The description does not attempt to add parameter semantics, which is fine because none exist. The baseline for zero parameters is 4, and the description fulfills that.

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 show the current MCP platform and adapter versions. It uses a specific verb ('Show') and a specific resource ('versions'), distinguishing it from sibling tools like toolkit_info or authenticate.

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—when the user needs version information—but does not explicitly state when to use this tool versus alternatives. For example, there is no mention of when to use show_version instead of toolkit_info or report_bug, although the purpose is clear enough that an agent can infer.

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 covered. The description adds valuable context by specifying exactly what state is returned, giving the agent a clear expectation of the tool's informational output.

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 core purpose and then enumerates the specific data categories. Every word earns its place, with no filler 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 the tool's low complexity (no parameters), strong annotations, and absent output schema, the description provides sufficient information. It tells the agent exactly what the tool returns and implies a read-only side-effect-free operation, making it complete for selection and 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 tool has zero parameters, so the baseline is 4. There are no parameter semantics to clarify, and the description appropriately focuses on the return value instead.

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 the current toolkit state' and enumerates the specific data included: installed MCPs, connection status, connected accounts, and catalog tool counts. This distinguishes it from sibling tools like authenticate or connect, which perform actions rather than report state.

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: whenever an agent needs an overview of the current toolkit state. It does not explicitly name alternatives or exclusion criteria, but the purpose is unambiguous and distinct from the action-oriented sibling tools.

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