Offshore Leaks (ICIJ)

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

Annotations already declare idempotentHint and destructiveHint; the description goes beyond by explaining the permanent vs. session-only behavior and that calling with no arguments returns a link. It doesn't detail response formats or potential errors, but it adds meaningful context about how the tool behaves in different invocation 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 compact and front-loaded, using three sentences to cover the target audience, two login modes, and invocation patterns. It is slightly dense but every clause adds useful information, and there is no 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 one optional parameter, no output schema, and useful annotations, the description covers the input semantics, the authentication flow, and both usage modes. It doesn't specify what the token response looks like or potential error cases, but for an authentication tool with strong annotations this is reasonably 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 schema only defines 'token' as a string with no description and 0% coverage. The description compensates fully by explaining that the token is a JWT, is optional, and that omitting it yields a login link while providing it performs a session-only authentication. This is exactly the semantic guidance an agent needs.

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 handles authentication/login for MCP.AI in IDE agents, explaining that it can provide a login link or accept a JWT token. It effectively describes the tool's purpose without being a tautology, though it does not explicitly distinguish itself from sibling tools like '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 concrete usage instructions: add the token to the server config for a permanent connection, or pass the token for a session-only login, and call with no args to get the link. It gives clear context and invocation patterns, but doesn't explicitly state when to avoid this tool or name 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 declare readOnlyHint and idempotentHint, and the description adds valuable behavioral context by detailing the two possible return states: all connected vs missing credentials. This goes beyond the annotations by describing output conditions.

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 two-sentence description is efficient and front-loaded, with the main purpose in the first sentence and additional details in the second. No wasted words.

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?

As a simple, parameterless tool with no output schema, the description sufficiently covers the key output scenarios (authenticated with empty pending, or connect_url with per-install URLs). The annotations cover safety, so this is 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 takes zero parameters, and the schema is empty. Per the rubric, a baseline of 4 applies. The description appropriately focuses on return behavior rather than parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Returns connection status and URLs.' It distinguishes from sibling 'authenticate' by focusing on status rather than initiating authentication, and the specific conditions (authenticated:true vs connect_url) make it uniquely identifiable.

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 checking connection status, but does not explicitly state when to use it over alternatives like 'authenticate.' There is no mention of exclusions or alternative tools, so the usage context is implied rather than 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 provide readOnlyHint=false and openWorldHint=true, but the description adds crucial behavior beyond that: invoke works even when the MCP is not installed, runs one-off without adding to the toolkit, returns connect links for credential needs, and returns checkout/top-up links for payment. It also states that writes require workspace owner/admin and that prompt library links open without login. This is substantial context not captured by 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, long block but every sentence contributes useful information about the many actions and behaviors. It is front-loaded with the overall purpose, though it could be better structured with bullets or separate sections for the MCP catalog flow vs the prompt library. It is not overly verbose, but its length is at the edge of acceptable.

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 14 actions and no output schema, the description covers most behavioral outcomes: describe returns a full profile, invoke returns connect/checkout links, publish_prompt returns a shareable link, and list_tools enumerates callable tools. Minor gaps remain (e.g., 'resume' is only listed without explanation, 'immediate' param is not described), but overall it is sufficiently complete for the 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?

Schema description coverage is 0%, so the description must compensate. It explains the core parameters (action, mcp_id, tool_id, arguments) and some prompt-related params, but leaves many others undocumented (e.g., immediate, limit, prompt_targets, prompt_category, request_details). The description does not systematically map all 23 parameters, leaving gaps that the schema also does not fill.

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 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It goes on to enumerate the core actions (search, describe, invoke, install, etc.) and the prompt library, making the tool's multi-purpose nature explicit and distinct from siblings like authenticate or toolkit_info.

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

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

The description provides explicit guidance on when to use each action and how they relate: 'Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile ... → invoke RUNS that tool.' It also gives clear when-not guidance: 'Use install only to make an MCP PERMANENT in the active toolkit; prefer invoke for a single/occasional use.' This strongly differentiates the 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 declare readOnly, idempotent, non-destructive; the description adds meaningful context: platform-hosted, no credentials, pay-per-query with prepaid credit, public-access data only, and LGPD data-controller responsibility. 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 three sentences, front-loaded with the main purpose, followed by access/payment and legal context. It is reasonably tight, though the LGPD sentence adds length without operational detail.

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?

No output schema and no parameter explanations leave gaps: the agent cannot know what NodeID refers to, what completo controls, or what the result looks like. The description covers purpose and data nature but not enough operational detail for confident 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 description coverage is 0% and the description does not explain NodeID, Nome, or the optional completo boolean. The only indirect hint is 'verifica se um nome aparece', leaving required parameters ambiguous for invocation.

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 checks whether a name appears in the ICIJ Offshore Leaks database (offshore structures), with explicit compliance/AML purpose. This specific verb+resource distinguishes it from the unrelated sibling tools (authenticate, marketplace, etc.).

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 frames usage for compliance and AML due diligence, states no credentials are needed and queries are paid with prepaid credit, and clarifies the data is public rather than private/confidential. It does not name explicit alternative tools or when-not-to-use scenarios, but the context is clear enough.

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 annotations (not read-only, idempotent, not destructive), the description adds that the conversation array should be included for reproduction, which is a useful behavioral hint. However, it does not disclose what effects reporting has, such as ticket creation or notification to developers.

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 sentences, directly to the point. The purpose is stated first, and the conversation instruction is a specific, actionable detail. No redundant wording.

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 (3 params, no output schema), the description covers the tool's core purpose and one key usage requirement, but it omits explanation of the 'context' parameter and any expected response or outcome. Enough for basic usage but not 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?

The description clarifies that 'message' is the content of the bug report/feedback and that 'conversation' should contain recent messages (stored as a string, despite being called an array). The 'context' parameter is not mentioned, and schema has no descriptions (0% coverage), so this is 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?

Clearly states the function: 'Report a bug, missing feature, or send feedback.' The verb 'report' and the resources (bug, missing feature, feedback) distinguish it from sibling tools like authenticate or connect, which serve different purposes.

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 user-facing issue reporting, but it does not explicitly state when to use it instead of alternatives or mention any exclusions. The instruction to include conversation for reproduction gives some context, but no explicit comparisons to sibling tools are 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Show' aligns with these. The description adds scope detail (platform and adapter versions) but does not disclose additional behavioral traits such as return format or error 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?

The description is a single sentence with no unnecessary words, fully front-loaded and clearly stating the purpose without any 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 zero-parameter, read-only version query, the description fully covers the tool's purpose. No output schema is present, but none is needed 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?

There are zero parameters, so the baseline is 4. The schema has empty properties, and the description correctly adds no parameter details since none exist.

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 the specific verb 'Show' and clearly identifies the resource: 'current MCP platform and adapter versions.' This is distinct from sibling tools like authenticate and marketplace, which have different purposes.

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 context is clear: this tool is for viewing version information. No explicit when-not or alternatives are mentioned, but no sibling tool serves a similar function, so the implicit guidance 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 already cover readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well established. The description adds return-value detail (state, connections, accounts, tool counts) but no additional behavioral traits like rate limits or prerequisites. With annotations present, this is within the expected range.

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, front-loaded sentence that efficiently communicates the full scope of the tool. No redundant or extraneous words, and the structure makes the return content immediately clear.

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 tool with no parameters and no output schema, the description fully describes the return value (installed MCPs, connection status, connected accounts, catalog tool counts). This is enough for an agent to correctly select and invoke 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 tool has zero parameters, so the schema coverage is trivially 100%. The description doesn't need to explain parameters, and the baseline for zero-parameter tools is 4. No additional parameter semantics are 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 with a specific verb and resource: 'Returns the current toolkit state' and details exactly what that includes (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from siblings 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?

The description gives no explicit when-to-use guidance or alternatives to consider. It relies on the reader to infer that this is for checking toolkit state, but it doesn't contrast with show_version or other sibling tools. The purpose is clear enough that a 3 is appropriate, but a 4 would require explicit context.

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