Comgás: Download de 2ª Via

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

Annotations indicate idempotentHint=true, readOnlyHint=false, and destructiveHint=false, and the description adds context beyond these: it explains the flow of logging in, copying a token, and the difference between permanent and session-only connections. It doesn't contradict annotations and provides useful behavioral details like requiring a browser login for the token.

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 opens with context, then clearly lists the three invocation scenarios. Each sentence serves a purpose, and the options are front-loaded. There is no redundancy, but it could be tightened by removing minor phrasing like 'copy the access token.' Overall, it's concise and easy to parse.

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 an authentication tool with no output schema, the description covers the essential aspects: how to authenticate (browser), what to do with the token (config or session), and the behavior of calling with no args. It doesn't detail return values or error handling, but those are not required, and the description gives enough context 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 has one parameter 'token' with no description (0% coverage), but the description compensates by explaining that the token is a JWT, how to pass it for session login, and that omitting it returns a login link. It clarifies the optional nature of the token and its purpose, adding meaning beyond the raw 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 the tool's purpose: authenticating MCP.AI for IDE agents. It specifies the verb (authenticate), the resource (MCP.AI), and the audience (IDE agents like Cursor). It also distinguishes from siblings by focusing solely on authentication, not other actions like connecting or reporting bugs.

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 method: permanent via config header, session-only via token argument, or no args to get a link. It explains the recommended approach and differentiates between options, though it doesn't explicitly address when not to use this tool versus alternatives. This is clear enough for an agent to decide how to invoke 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds behavioral context about the two output states (authenticated vs missing credentials) and the returned URLs, which goes beyond 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 two sentences, front-loaded with the core purpose, and each sentence adds specific value—covering both normal and missing-credential scenarios without 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?

For a zero-parameter status tool, the description covers the key outputs (authenticated, pending[], connect_url, per-install URLs) sufficiently. It could elaborate slightly on what 'pending[]' represents but is otherwise 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?

There are no parameters, so the baseline of 4 applies. The description doesn't need to add parameter info; it focuses on outputs, which is appropriate.

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 conditions detailed. It is a distinct status check compared to siblings like 'authenticate' or 'marketplace', so it differentiates well.

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 (to check connection status) but does not explicitly state when to use versus alternatives or provide preconditions. It describes output scenarios but lacks direct guidance on selection.

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 and non-destructive behavior. The description adds context about no platform credentials, prepaid pricing, official source, and LGPD data controller responsibilities, going beyond the bare safety profile.

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 compact three-sentence paragraph that front-loads the core purpose. The LGPD sentence adds legal context but is somewhat verbose; overall it's efficient and not bloated.

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 purpose, pricing, official source, and data governance, but it omits parameter meanings and return format. Since there is no output schema, this gap is notable; the tool is simple enough that the description is adequate 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?

With 0% schema description coverage, the description must explain parameters, but it never mentions codigo_usuario or cnpj. The tool name hints at 'user code', but no meaning or usage guidance is provided, leaving parameter semantics largely ambiguous.

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 downloads a second invoice ('Download de 2ª Via') from Comgás via an official source. The verb 'Download' and resource 'Comgás' are specific and distinguish it from unrelated sibling tools 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 implies the tool is for obtaining Comgás second invoices, mentioning official source and prepaid credit. Since sibling tools are unrelated, it doesn't need exclusions, but it stops short of explicitly saying 'use this when you need X'.

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 well beyond the sparse annotations, disclosing key behaviors: invoke runs uninstalled MCPs one-off, returns connect/checkout links for auth/payment, requires workspace owner/admin for writes, and includes the one-off install behind invoke. This gives the agent a realistic model of side effects.

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 every sentence carries useful information. It is front-loaded with the core purpose and flow, and the length is justified by the tool's complexity. Some restructuring into bullets could improve readability, but it is not redundant.

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 spans 14 actions, 23 parameters, and no output schema, the description covers the main workflows, auth/payment edge cases, permission requirements, and the prompt library. It lacks explicit response-shape information, but for an agent the key operational details are 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?

With 0% schema parameter coverage and 23 parameters, the description compensates for the most important ones (action enum values, mcp_id, tool_id, prompt_slug, prompt_vars) but leaves many others (limit, immediate, tier_slug, cancel_reason, prompt_targets, etc.) undocumented. Partial compensation only.

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 defines the tool as the mcp.ai marketplace catalog and execution engine, with a clear core flow (search → describe → invoke). It differentiates itself from sibling tools by positioning itself as the central hub for discovering and running MCPs, as well as a prompt library.

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 guidance on when to use each action: 'Use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use.' It also explains the core flow, flags admin requirements for writes, and distinguishes report_bug/request_mcp for feedback/new-MCP needs.

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, non-destructive, idempotent behavior. The description adds the useful detail that the conversation array is needed for reproduction, but does not disclose what happens after submission, confirmation, or any side effects.

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 focused sentences, front-loaded with the core purpose. Every word adds value, with no fluff 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?

For a simple three-parameter tool, the description is mostly adequate but incomplete: it omits what should go into the required 'message' parameter and the optional 'context' parameter. No output schema exists, so return behavior is not specified.

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 the 'conversation' parameter's purpose, but leaves the required 'message' and optional 'context' parameters entirely unexplained.

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 reports bugs, missing features, or feedback, using a specific verb and resource. It also instructs including the conversation array for reproduction, distinguishing it from unrelated siblings like authenticate and 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 explicitly identifies when to use the tool (bug, missing feature, feedback), but does not mention when not to use it or name alternatives. Since sibling tools are unrelated, 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 already declare readOnlyHint=true and idempotentHint=true, and the description aligns with a safe, read-only operation by using 'Show'. The description adds the specific detail that both platform and adapter versions are returned, which is not fully captured in annotations. It offers some additive context beyond the structured data.

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 with no fluff. Every word earns its place, and it instantly conveys the tool's function. Properly sized for the tool's simplicity.

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 version-querying tool with no parameters and no output schema, the description is fully sufficient. It tells the agent exactly what to expect without needing extra details like return format. The tool is straightforward, and the description covers everything needed for correct 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?

This tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters since there are none, and the schema already covers everything with no parameters. No additional semantic information is required 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 'Show the current MCP platform and adapter versions' clearly states the action (show) and the specific resource (current MCP platform and adapter versions). It is distinct from sibling tools like 'authenticate' or 'connect', which serve different purposes. This is a specific and unambiguous 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?

The description implies when to use the tool—whenever a user needs to check the versions of the MCP platform and adapters. There are no alternatives or exclusions, but the simplicity of the tool makes the usage obvious. It provides a clear context without needing explicit 'when not to use' guidance, though it doesn't explicitly mention 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=true, idempotentHint=true, and destructiveHint=false. The description adds specific return content (states, accounts, counts), which goes beyond the annotations and clarifies what the user will receive.

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 conveys all necessary information without redundancy. 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 simple, parameterless, read-only tool with no output schema, the description fully explains what the tool returns. It is complete for the tool's complexity level.

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 of 4 applies. The description adds no parameter details because there are none to explain.

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 action ('Returns the current toolkit state') and specifies the exact content: installed MCPs, connection status, accounts, and catalog tool counts. This distinguishes it from siblings like show_version and 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?

The context implies this tool is used to inspect toolkit state, but there is no explicit guidance on when to use it over alternatives or any exclusions. For a simple informational tool, the absence of explicit alternatives is a minor gap.

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