ECAC: DCTF WEB

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

The description adds practical behavior details beyond the annotations: it explains how the login flow works, the difference between a permanent configured connection and a session-only pasted token, and what the no-args call returns. It does not describe the exact return format or the failure behavior for invalid/expired tokens.

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 somewhat long but each sentence earns its place: it states the login method, config-based permanent option, session-based option, and exactly how to call with and without arguments. There is a bit of extra context ('MCP.AI for IDE agents...') that helps targeting but is not strictly necessary.

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 only one schema property and no output schema, a summary of the full login flow is necessary, and the description covers it: get token in browser, use one-time token, or omit token for the link. It is missing only an explicit statement of what the tool returns, which would make it 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 schema only defines token as an optional string with no additional description. The description compensates by explaining that the token is a JWT access token, that it is passed after the user pastes it, and that omitting it triggers the link-returning flow. It could add expected token format or validation behavior, but it already gives substantial practical meaning.

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 action: authenticate with MCP.AI by logging in through the browser and providing or obtaining an access token. It is specific about the two call modes, which distinguishes this tool from siblings like connect 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 explicit usage guidance: use no args to get the login link, or pass { token: "<jwt>" } once the user has pasted an access token. It also recommends the permanent config-based Authorization header over the session-only approach. It does not explicitly say when to avoid this tool versus other sibling tools.

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 state readOnly and idempotent. The description adds behavioral details: returns authenticated:true and empty pending[] when all connected, and provides connect_url and per-install URLs when missing credentials. This is beyond annotations, giving clear 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?

The description is concise, using clear conditional statements to explain behavior. It is structured logically and easy to grasp.

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?

Covers main scenarios (all connected, missing credentials) but could mention partial connectivity or other states. Still, it provides enough context for typical use.

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 (openWorldHint false, empty schema properties). The description implicitly confirms no parameters needed since it just returns status. This is unambiguous.

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, which is specific and distinct from sibling tools like authenticate (which presumably performs authentication) or show_version. It identifies the resource being checked and the type of output.

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 conditional scenarios ('when all providers are connected' vs 'when credentials are missing'), which implies it should be used to check connection state flagged. However, it does not explicitly contrast with alternatives like 'authenticate', which might be a complementary tool. Clear enough context but lacks explicit exclusions.

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, and the description complements this by adding cost-per-query, no platform credentials required, and LGPD data control obligations. It reinforces the read-only nature and adds operational context without contradicting any 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 concise paragraph that front-loads the purpose, then adds payment and legal context. Each sentence contributes useful information, though the legal disclaimers could be seen as slightly overlong, but they are relevant to responsible use.

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?

Despite good coverage of the tool's purpose and compliance aspects, the description omits any guidance on parameter semantics or expected input values. With 12 parameters and no output schema, this is a significant gap that leaves the agent unable to construct valid requests.

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 has zero parameter descriptions and the tool description provides no explanation of the 12 parameters (e.g., pkcs12_cert, numero_recibo, data_final_apuracao). The agent is left with no guidance on how to populate required fields, making the tool effectively unusable without external knowledge.

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 performs consultations (consulta) on official Brazilian DCTF data via the ECAC system. It distinguishes itself from generic sibling tools (authenticate, connect, etc.) by specifying the domain and resource, and notes it provides the same non-confidential information available to citizens.

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 (consulting DCTF data from official sources) and mentions practical details like prepaid credit and LGPD responsibilities. However, it does not explicitly state when not to use it or name alternative tools, though siblings are not directly comparable.

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, the description discloses important runtime behaviors: invoke runs a tool one-off even when the MCP is not installed, missing credentials cause invoke to return a connect link, empty wallets cause a checkout/top-up link, and search/describe flag installed_in_toolkit vs installed_in_workspace. It does not contradict the annotations (readOnlyHint=false, destructiveHint=false), and actually enriches them with auth, billing, and permission context.

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 text is dense and front-loaded: the opening sentence establishes the tool's identity, and the search→describe→invoke flow is presented before auxiliary actions. It is long, but the 14-action scope justifies the length; minor structural improvement (bullets or separation between MCP marketplace and prompt library) would make it even easier 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?

For a high-complexity tool with no output schema, the description impressively covers core flows, auth and payment edge cases, write permissions, installed flags, and the prompt library. It does omit details on a few actions (resume, uninstall specifics, subscribe/cancel semantics) and does not describe return formats, leaving some gaps for the agent to discover at runtime.

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 23 parameters and 0% schema description coverage, the description works hard to explain the action enum and the core mcp_id/tool_id/arguments workflow, including prompt_slug and prompt_vars semantics. However, it still leaves several parameters undocumented (immediate, tier_slug, cancel_reason, conversation, report_context, etc.), so it compensates well for the main flow but not exhaustively for every 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 identifies the marketplace as the official mcp.ai catalog and execution layer, walking through the core search → describe → invoke flow and enumerating every action (install, list_tools, subscribe/cancel, report_bug, request_mcp, prompt-library operations). This positions it distinctly from siblings like authenticate/connect by framing it as the catalog/runner rather than an auth/connection helper.

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 selection guidance: 'prefer invoke for a single/occasional use' and 'use install only to make an MCP PERMANENT in the active toolkit', while also explaining when request_mcp fits ('when nothing fits') and noting that list_tools lists what is callable right now. It further clarifies that writes require workspace owner/admin, which helps the agent decide if the operation is even permitted.

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 the instruction to 'Include the conversation array with recent messages for reproduction,' which hints at the data being submitted. Annotations already signal non-read-only and idempotent behavior, and the description does not contradict these. However, it does not disclose other potential side effects or post-submission outcomes beyond what is implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no redundancy. The first sentence states the purpose, and the second gives a key usage instruction. Every word earns its place.

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 relatively simple tool with three parameters and no output schema, the description covers basic purpose and one usage detail. However, it omits explanation of the required 'message' parameter and any information about what happens after submission (e.g., where the report goes), leaving gaps in completeness.

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 coverage is 0%, so the description carries full responsibility for explaining parameters. It only mentions the 'conversation array', leaving the required 'message' and optional 'context' parameters unexplained. This is insufficient for an agent to correctly populate all fields.

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 'Report a bug, missing feature, or send feedback,' using a specific verb and resource. It unambiguously identifies the tool's function without ambiguity, distinguishing it from sibling tools that likely handle other tasks.

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

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

Usage is implied through the purpose statement—users understand they should use this tool for reporting bugs or feedback—but there is no explicit 'use when' versus alternatives, nor any exclusions. Context is present but not elaborated beyond the core function.

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, destructiveHint=false, providing a safe profile. The description adds context about what is displayed (platform and adapter versions), which is beyond the annotations. It does not contradict annotations, so no red flags.

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, complete sentence that front-loads the purpose. There is zero verbosity, every word earns its place.

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 extreme simplicity (zero parameters, no output schema, static informational output), the combination of description and annotations is fully complete. It covers what the tool does and its safe nature. A 5 is reserved for tools with more complexity but would be overkill here.

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 perfect at 100%. With no parameters, the description has no need to explain parameter details; the baseline of 4 is appropriate given the simplicity.

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 current MCP platform and adapter versions. The verb 'show' and resource 'versions' are specific. There are no siblings with similar version-display functionality, so it stands distinct.

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 tool is a simple read-only informational tool with no parameters and no prerequisites. There is no explicit guidance on when to use it versus alternatives, but the context is inherently clear—it is for checking versions. It does not need exclusionary 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 and idempotentHint, so the description doesn't need to repeat that. It adds detail on what state is returned (connection status, accounts, tool counts), which gives helpful context without contradicting 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, concise sentence that front-loads the action ('Returns') and lists specific content. Every word adds value with 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?

The description covers the key aspects of what the tool returns, sufficient for a simple info tool without an output schema. It could mention whether it includes errors or connection failures, but it explicitly lists connection status, which implies that.

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 there is nothing to explain. The description correctly focuses on the return value, and the high schema coverage (though trivial) makes parameter explanation unnecessary.

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 current toolkit state, listing specific contents: installed MCPs, connection status, accounts, and 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 implies usage for checking overall toolkit status, which is natural for an info tool. It does not explicitly mention when not to use it or alternatives, but given its read-only nature and sibling set, the context is clear.

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