ECRVSP ATPV (Intenção de Venda): Incluir

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds meaningful behavioral context: browser login flow, permanent vs session-only token handling, and the non-expiring nature of the config header approach. It does not mention token storage or error behavior, but the description and annotations together give a solid transparency profile 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 three sentences with a logical flow: purpose, recommended permanent approach, and session-only fallback. It is slightly wordy but every sentence adds distinct, actionable information. The use of 'Best:' and 'Or' structures the decision 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 tool with one optional string parameter and no output schema, the description covers the main behavior, both invocation modes, and the expected workflow. It lacks explicit return-value/error details, but the auth flow is sufficiently complete for an agent to invoke it correctly.

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 an optional 'token' string with no description, so the description carries the full explanatory burden. It clearly explains that the token is a JWT pasted by the user, and that omitting arguments returns the login link. This fully compensates for the 0% schema description coverage.

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

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

The description clearly states that the tool authenticates the user for MCP.AI by logging in through the browser and obtaining an access token. It specifies the two concrete actions: outputting a login link or accepting a pasted JWT token. This differentiates it from siblings like connect or marketplace by focusing specifically on authentication flow.

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: prefer adding the token as a permanent Authorization header in the server config, or use a session-only login by pasting the JWT. It also explains when to call with no args (to get the link) versus with a token. This is an exemplary level of practical instruction.

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 non-destructive. The description adds value by explaining the return values in different states (authenticated true vs connect_url), which is not covered 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 two sentences, clear, and front-loaded with the primary purpose. Every sentence adds value: the first states the action and the second explains conditional return values.

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 parameters, no output schema, and simple functionality, the description covers the key states (authenticated vs pending) and the response structure (connect_url). It's adequate for an agent to know what to expect. Could mention that it's a status check only, but annotations already imply read-only.

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 doesn't need to explain parameters but provides meaningful output semantics related to the connection status.

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 behavioral details about authenticated state and pending connections. It differentiates from siblings like 'authenticate' by focusing on status rather than establishing connections, making the purpose unambiguous.

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 describes two scenarios—all providers connected vs missing credentials—providing context on expected outcomes. However, it does not explicitly state when to use this over alternatives like 'authenticate', though the read-only nature is 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?

The description explicitly states 'Incluir' (include/insert) which implies a write operation, but the annotations declare readOnlyHint: true. This is a direct contradiction. Therefore, the description fails to align with the annotation and receives a score of 1.

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 short and to the point, but it is dense and mixes technical, legal, and business information in one sentence. It covers the payment model and data source but lacks clear structure and front-loading of the core action. No redundancy, but could be better organized.

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 21 required parameters, no output schema, and a tool that appears to both create and query, the description is woefully incomplete. It fails to explain the workflow (how 'incluir' and 'consultar' interact), what credentials are needed (a3, a3_pin, login_senha), or what the response contains. The tool's complexity demands much more detail.

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 provides zero explanation of the 21 parameters. With 0% schema coverage, the description must compensate but does not. The prefixes (comprador_, proprietario_) offer only weak hints, and the description adds no semantic meaning beyond parameter names.

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 domain (Brazilian vehicle sale intention/ATPV) and that it includes and queries official sources. It distinguishes itself from generic platform tools (authenticate, connect, etc.) by naming the specific vehicle-related purpose. However, the dual action (incluir and consultar) is not fully clarified—it could be a write or read operation or both, and the description doesn't explicitly separate these behaviors.

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 mentions it is hosted by the platform, uses pre-paid credits, and queries official Brazilian sources, which gives some usage context. However, there is no explicit guidance on when to use this tool versus alternatives, nor any conditions or exclusions. It doesn't state typical scenarios or when not to use it.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint=false, destructiveHint=false): invoke's one-off behavior without toolkit bloat, the connect-link-on-auth and checkout-link-on-empty-wallet retry semantics, 'Writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin', and the installed_in_toolkit vs installed_in_workspace distinction. No contradiction with annotations — uninstall/cancel being non-destructive flags is consistent with the description not claiming data destruction. Credential/permission requirements are disclosed in detail.

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 250+ word description is front-loaded with the core purpose and three-step flow, then branches to invoke's key behavior, install vs invoke, auxiliary actions, and the prompt library. For 23 params and 14 actions, the density is justified — every sentence covers a distinct actionable concept. Minor redundancy: 'pontualmente' repeats the one-off idea already stated, and the prompt-library section (while necessary) adds a second semantic domain that lengthens the text.

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 extreme complexity (23 params, 14 actions, no output schema, no required params), the description is remarkably thorough: it covers auth requirements, persistence semantics (invoke vs install), billing/retry flows, installed flags, and the entire prompt sub-system. Gaps: the 'resume' action is never mentioned, and exact invocations/response formats for search results are assumed rather than specified. Still, a tool this complex rarely gets such complete prose coverage — only the resume gap and lack of search-return description hold it back from a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description compensates strongly: it maps the action enum to real behaviors (describe returns 'one MCP's full profile... so you pick the right tool_id → invoke'), explaining how tool_id, arguments, mcp_id, and query relate. The prompt-library actions (search_prompts, get_prompt, publish_prompt) are also given meaning. However, roughly half the params (prompt_title, prompt_category, request_details, cancel_comment, tier_slug, immediate, conversation) are not individually explained in prose, relying on inference from action context. Strong coverage for the core flow, partial for the periphery.

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 role: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them' with a specific search→describe→invoke flow. However, it is an overloaded dispatch tool covering 14 actions across two domains (MCP marketplace AND a prompt library), which blurs a single-purpose identity. The name 'marketplace' plus the prompt-library extension dilutes the core purpose.

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

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

Excellent when/when-not guidance: 'prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT', 'list_tools lists what is callable right now', and explicit mapping of each action (subscribe/cancel→billing, report_bug→feedback, request_mcp→build new). It also names the alternative discovery verbs ('find an MCP that does X') so the agent knows what queries trigger search. This is textbook sibling differentiation.

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 idempotent behavior and no destructive side effects. The description does not contradict these but also adds little beyond the input guidance. It doesn't disclose possible side effects like creating a ticket or sending an email, but given idempotentHint is true)Skip. It adds the context that conversation is needed for reproduction, which is a mild behavioral hint but not substantial.

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 that front-load the purpose and provide one key usage instruction. No fluff; every part 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 simple feedback tool with 3 parameters and no output schema, the description is adequate. It explains the core action and the reason for the conversation parameter, though it doesn't mention outcomes or optional context. Overall sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must explain parameters. It explains the conversation parameter's purpose but leaves 'message' and 'context' implicit. Message is inferable as the bug/feedback content, but context is not addressed. Partial compensation for missing 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: 'Report a bug, missing feature, or send feedback.' It uses a specific verb (report/send) and specific objects (bug, missing feature, feedback), and is clearly distinct from sibling tools like authenticate, connect, or marketplace.

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

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

It tells when to use the tool (report a bug, missing feature, or send feedback) and gives a specific instruction to include the conversation array for reproduction. However, it does not explicitly mention when not to use it or provide alternatives, though 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?

Annotations declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate safety. It adds value by specifying the output scope (both platform and adapter versions), which is beyond the structured annotation data. No contradictions found.

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 with zero wasted words. It conveys the entire purpose immediately and is appropriately concise for a read-only informational tool.

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 params, no output schema, simple read-only purpose), the description fully covers what the agent needs to know. It names the exact information provided (MCP platform and adapter versions), 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, and schema description coverage is 100% (empty properties). The description adds nothing about parameters because there are none, which meets the baseline for parameter semantics.

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

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

The description uses a specific verb 'show' and names the resource ('current MCP platform and adapter versions'). It clearly distinguishes itself from sibling tools like marketplace or connect 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?

No explicit guidance on when to use this tool versus alternatives. However, given the simplicity of the tool, the intended use case is implied (checking platform compatibility or version details). It lacks any exclusion criteria but is not misleading.

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 already declare this as a read-only, idempotent, non-destructive operation. The description adds transparent output details beyond those annotations, specifying what state is reported and how catalog tools are counted, which helps set expectations.

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 states the purpose first ('current toolkit state') and then adds details in a compact list. Every clause contributes useful information with no 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?

For a zero-parameter, read-only informational tool, the description sufficiently covers what the caller receives: installed MCPs, connection status, accounts, and catalog tool counts. It lacks detailed formatting/type info, but the output is simple enough that this is not a meaningful gap.

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 parameter descriptions are unnecessary. The baseline of 4 applies because there is nothing the description needs to add to the 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 states a specific verb ('Returns') and resource ('current toolkit state'), then enumerates the exact output categories: installed MCPs, connection status, accounts, and exposed catalog tool counts. This clearly distinguishes it from sibling tools like authenticate 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?

The description clearly implies this tool is for inspecting the current toolkit state, which is distinct from the action-oriented sibling tools. It does not explicitly list exclusions or alternatives, but the intended usage context is unambiguous.

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