AML (Vínculos Societários)

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

The description contradicts the openWorldHint annotation. openWorldHint is set to false, but the description states it consults 'bases e fontes oficiais' (official databases) for public information, meaning results depend on external real-world data. This is an annotation contradiction. Additionally, it doesn't describe return format or pagination, but the contradiction is the primary issue.

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, front-loaded with the main purpose, followed by contextual and legal information. Each sentence adds value; it's not padded. A short paragraph, easy to scan.

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?

The tool is fairly simple, but the lack of explanation for the 'completo' parameter creates a gap. The description also doesn't mention what the output looks like, although it implies mapping of corporate links. Given no output schema exists, the description should be more explicit about return values and the effect of 'completo'. The open-world contradiction also reduces trust.

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 0% description coverage, and the description only mentions CPF as the input. The optional 'completo' boolean is never explained, leaving its behavior ambiguous. The description partially compensates for Cpf but not for 'completo'.

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 with a clear, specific statement: 'Mapeia vínculos societários de uma pessoa física para diligência antilavagem (AML) a partir do CPF.' This identifies the verb (map), the resource (corporate links of an individual via CPF), and the purpose (AML due diligence). It clearly differentiates from sibling tools like authenticate or show_version.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides context that the tool is hosted on the platform, requires no credentials, and is pay-per-query with prepaid credit. It also clarifies the data source (public official databases), which helps the agent decide when to use it. However, it does not explicitly state exclusions or alternative tools, though none are relevant among the 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 description adds meaningful behavioral context beyond the annotations: it reveals the distinction between permanent (config) and session-only (paste) authentication, states that the config method is non-expiring, and explains that calling with no args returns a link. This complements the idempotentHint and destructiveHint annotations without contradiction.

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 slightly long but well-structured. It leads with the core purpose, then explains two usage paths with clear formatting. Every sentence adds useful information, though the phrasing could be tightened without loss.

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 one optional parameter and no output schema, the description covers the main execution flow: how to obtain a token, the two ways to use it, and what happens when no args are given. It does not mention error cases or return values, but these are less critical for such a simple 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 a 'token' string with no description. The description compensates by explaining the token is a JWT ('{ token: "<jwt>" }'), that it is optional (can call with no args), and that it is used for session-only login. This gives critical meaning that the schema lacks.

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 is for authentication ('log in in the browser, copy the access token'), and it describes the process for IDE agents like Cursor. It is distinct from siblings by detailing the token-based login flow, but it does not explicitly name alternatives or compare with 'connect', so it lacks strong sibling differentiation.

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 explains two usage modes: adding the token to config for a permanent non-expiring connection, or pasting it for a session-only login. It explicitly recommends the config method ('Best: ...') and explains when to call with no args to get the link. However, it does not discuss when NOT to use the tool or compare with alternative tools, so it falls short of full explicit 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?

The description goes beyond the readOnlyHint annotation by detailing exact behaviors: it returns authenticated:true and empty pending[] when all providers are connected, and connect_url plus per-install URLs when credentials are missing. This conditional behavior is valuable and not conveyed by annotations alone.

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, front-loaded with the primary action, and each sentence provides meaningful detail about output states. No filler or repetition.

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?

The description covers the two main states (all providers connected vs. missing credentials) and implies the intermediate state through pending[]. It lacks an explicit description of partial connection states or output format, but for a simple read-only status tool, it is adequately 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 no parameters, so the description cannot add parameter meaning. Per rubric, zero-parameter tools receive a baseline of 4, which is appropriate here.

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 it 'Returns connection status and URLs', specifying a concrete resource and output. It differentiates from sibling tools like 'authenticate' by focusing on status checking rather than initiating authentication.

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 the tool (to check connection status) and provides context through conditional outcomes. It does not explicitly name alternatives or exclusions, but the sibling tool list makes the context clear.

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?

Discloses important behavioral details beyond the annotations: invoke runs tools one-off without installing, returns connect or checkout/top-up links on credential/payment failures, and requires workspace owner/admin for writes. Also explains the installed_in_toolkit vs installed_in_workspace flags, giving a realistic picture of side effects and prerequisites. No contradiction with readOnlyHint=false; the description openly acknowledges that install/uninstall/subscribe/cancel are mutations.

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 dense; the length is warranted given the tool's 14 actions and 23 parameters. It front-loads the core flow and then covers auxiliary actions and the prompt library. Though a bulleted structure would improve scannability, each sentence contributes unique value without 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?

For a tool of this complexity with no output schema, the description is exceptionally complete: it covers search/describe/install/invoke, billing actions, bug reports, MCP requests, and the prompt library. Minor gaps include the 'resume' action and some parameters like tier_slug/immediate, but the core decision paths an agent needs are fully articulated.

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?

Since the schema has 0% coverage, the description compensates meaningfully by explaining the core parameters (action, mcp_id, tool_id, arguments) and the prompt_* fields. It maps actions to parameter usage in the flow. However, it does not explain every parameter, such as limit, immediate, tier_slug, or resume-related fields, leaving some parameters under-documented for full self-service use.

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 explicitly states the tool is 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' using specific actions (search, describe, invoke, install) and covering both MCP discovery and execution. It clearly differentiates from siblings by defining its role as the central catalog/runtime, while siblings like authenticate, connect, and report_bug are narrowly scoped utilities.

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?

Offers explicit guidance on when to use invoke (one-off, works even for uninstalled MCPs) versus install (permanent toolkit addition), and names alternatives like request_mcp for missing capabilities. It also identifies list_tools for currently callable tools and distinguishes the prompt library as separate from MCP tools, providing a clearly mapped decision flow.

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 non-read-only, idempotent, non-destructive behavior, so the description doesn't need to restate that. It adds context about requiring conversation data for reproduction, which hints at how the report might be used. However, it doesn't explain side effects (e.g., whether a ticket is created) or further behavior, so it provides moderate added value beyond 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 sentence that front-loads the purpose and immediately gives a key usage instruction. It is concise with no filler or redundant content, earning high marks for efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with 3 parameters and no output schema, the description is adequate but leaves gaps: it does not explain the 'context' field, and the overall workflow (e.g., what happens after reporting) is unclear. Sibling tools are unrelated, so no special contextual comparisons are needed, but the description could be more complete for a new 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 compensate. It clarifies that 'conversation' should contain recent messages for reproduction, adding meaning beyond the schema's bare string type. However, it does not address the 'context' parameter or elaborate on the required 'message' parameter beyond its obvious meaning, leaving partial 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 function: 'Report a bug, missing feature, or send feedback.' This is a specific verb (report/send) plus a resource (feedback/bug report), and it immediately distinguishes itself from sibling tools like authenticate or marketplace. 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 implies when to use the tool (when reporting issues) but does not explicitly contrast it with alternatives or provide exclusions. It does add a usage hint about including the conversation array, which helps in preparing the input, but the 'when vs. when-not' 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds 'current' indicating it retrieves live version info, which is useful context. No contradictions 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 single, clear sentence that directly states the tool's function. It is front-loaded and contains no filler or redundant information.

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, no parameters, and no output schema, the description fully explains what the tool does. It mentions both platform and adapter versions, which is complete for this read-only 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 tool has zero parameters, so the baseline is 4. The description does not need to elaborate on parameter semantics since none exist, and the schema coverage is complete.

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 with a specific verb ('Show') and resource ('current MCP platform and adapter versions'). It distinguishes itself from sibling tools like 'toolkit_info' and 'marketplace' by focusing on version information.

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 for checking versions but does not explicitly state when to use this tool over alternatives or any exclusions. Since the tool is straightforward and no sibling overlaps, implied usage is acceptable 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context about the returned state's contents (connection status, accounts, catalog tool counts), providing behavioral transparency beyond the annotations. No contradictions.

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 packs in all necessary information without redundancy. It is front-loaded with the main action and lists the specific data points clearly.

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 introspection tool with no parameters and no output schema, the description is complete. It fully describes what the tool returns, and the annotations cover safety. No additional context is needed.

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 per the rubric. The description does not need to explain parameter semantics, and it correctly avoids inventing any.

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 with a specific verb ('Returns') and resource ('current toolkit state'), enumerating the exact information provided (installed MCPs, connection status, accounts, and catalog tool counts). This distinguishes it from siblings like show_version, which focuses only on version info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives. It does not mention scenarios where it would be preferred, prerequisites, or exclusions. The sibling tools (connect, authenticate, show_version) have overlapping but distinct purposes, yet the description provides no differentiation.

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