SUSEP: Empresas

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

Annotations already cover idempotency and non-read-only. Description adds behavioral context (browser flow, permanent vs session) without contradicting annotations. Does not detail side effects like token replacement, but idempotentHint mitigates concerns.

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, but somewhat run-on. Front-loaded with the main action (log in) and clearly separates the two methods. Could be broken into bullet points, but not overly verbose.

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 auth tool with one optional param and no output schema, the description covers the essential steps and outcomes (link vs token, permanent vs session). It omits error handling or post-auth verification, but overall adequate.

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 has 0% coverage, but description compensates by explaining the token param as a JWT and gives usage examples ({ token: "<jwt>" } and no args). Semantics are clear, though lacks format details such as expiration.

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: authentication for IDE agents via browser login. It distinguishes from siblings (connect, marketplace, etc.) by focusing exclusively on access token handling.

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 usage scenarios: permanent config header vs session-only token paste, and no-args mode to fetch the login link. Clearly tells the agent when to use this tool over 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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read-only nature is known. The description adds useful behavioral detail beyond annotations by explaining the conditional response fields (authenticated, pending, connect_url), which helps an agent anticipate connection-state negotiation.

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-loads the main purpose, and then adds the two key conditional behaviors. Every sentence contributes useful information with no filler or repetition of annotation fields.

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 status tool with strong annotations, the description covers the main response states and likely usage scenario. It does not explicitly describe partial-connection behavior or list every possible output field, but those are minor gaps for this 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 tool has zero parameters and an empty schema, so there is no parameter documentation burden. The description appropriately focuses on behavior instead, matching the baseline for a no-parameter tool.

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 a connection-status reporter ('Returns connection status and URLs'), which is distinct from an authentication action. It avoids tautology and communicates the core inspection purpose, though it does not explicitly name sibling tools as alternatives.

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 clear conditional guidance: when all providers are connected, expect authenticated:true and empty pending[]; when credentials are missing, expect connect_url and per-install URLs. It does not explicitly say when to use this over authenticate, but the states provide practical interpretation context.

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?

No annotations contradict the description (readOnlyHint:false is consistent with the described writes). The description adds rich behavioral context: invoke runs one-off even if not installed, external links are returned for auth/payment with a "retry after user opens" directive, and writes require owner/admin. Details like installed_in_toolkit vs installed_in_workspace flags and the mcp.ai/p/<slug> unauthenticated link behavior go well beyond the structured fields.

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 ~380-word wall of text with no paragraph breaks, bullets, or heading structure. It front-loads the core purpose, but the density and interleaving of catalog, auth, billing, permissions, and prompt library make it hard to scan. It also mixes Portuguese ("consulta um CPF", "pontualmente") into an English description, which is unprofessional and could confuse the agent. Every sentence adds information, but the lack of structure hurts usability.

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 a lot of ground: the search/describe/invoke workflow, one-off vs permanent installation, auth and top-up link flows with retry, permission requirements, and the prompt library sub-features. However, it omits behavior for actions like 'resume' and 'immediate', and gives no output/return shape. Given the tool's enormous scope, this is a strong but not perfect effort.

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 23 parameters with 0% schema description coverage, and the description names only a few (action, tool_id, mcp_id) in prose without documenting what they accept or their roles. It does explain conceptual flows (e.g., pick tool_id → invoke) and that {variables} get filled in prompt templates, but it never explains what limit, query, arguments, prompt_vars, immediate, conversation, or cancel_reason do. Given the scale of params, this is insufficient compensation for the missing schema documentation.

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 leads with a specific, unambiguous definition — "The official mcp.ai marketplace — the in-platform catalog of every MCP/tool" — then catalogs all 14 possible actions (search, describe, invoke, install, subscribe, etc.). It clearly differentiates the marketplace from the prompt library and explains the core search→describe→invoke flow. Although the TITLE field is null, the purpose is fully specified.

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 recommendations: "Use install only to make an MCP PERMANENT in the active toolkit; prefer invoke for a single/occasional use." It contrasts subscribe/cancel for billing, report_bug for feedback, request_mcp for new MCPs, and distinguishes search_prompts/get_prompt/publish_prompt for prompt text. It also flags permission requirements and credential/payment link flows. This is model guidance for when to use which action.

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 convey readOnlyHint=false, destructiveHint=false, and idempotentHint=true, indicating a safe but mutating action. The description adds the behavioral instruction to provide the conversation array, but does not disclose side effects (e.g., ticket creation) beyond that.

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 zero fluff. The key instruction about the conversation array is front-loaded.

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, the description covers purpose and one key parameter but omits explanation for 'message' and 'context'. With no output schema, the user is left wondering about the response format or confirmation.

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% and the description only explains the 'conversation' parameter (as a reproduction aid). The required 'message' and optional 'context' fields receive no clarification, leaving their meanings 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's purpose with a specific verb ('Report') and resource ('bug, missing feature, or feedback'). It is distinct from sibling tools like authenticate or show_version, making it 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 explicitly instructs to include the conversation array for reproduction, giving clear usage context. However, it does not mention when not to use it or point to alternatives, though the purpose is self-explanatory.

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, so the agent knows it's safe. The description adds no further behavioral context beyond what's present. It's adequate but not enriched.

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?

Single sentence, clear, and front-loaded. All words add value; no fluff.

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 tool with good annotations, the description is sufficient. It doesn't explain output format (missing output schema), but that's not critical for such a simple operation.

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 coverage is 100%. The description adds meaning by specifying what versions are shown ('MCP platform and adapter'), which is useful for the agent. Baseline 4 for no parameters 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 explicitly states the tool displays current MCP platform and adapter versions, using a specific verb ('Show') and resource ('MCP platform and adapter versions'). It clearly distinguishes from siblings like 'toolkit_info' (likely more comprehensive) 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 description implies use for checking versions, but does not explicitly state when to use it versus alternatives. Given no sibling descriptions, this is acceptable but lacks nuance.

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. The description adds meaningful behavioral context beyond those: the data is public/non-confidential, available to citizens from Brazilian official agencies, and the client is the LGPD controller. This clarifies the operational and legal nature of the query.

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 useful information packed in: purpose, hosting, billing, data provenance, and LGPD responsibilities. It is somewhat dense but contains no meaningless filler and front-loads the tool's core purpose.

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 query with one parameter, the description covers purpose, data source, credentials, payment, and legal context. However, with no output schema, it does not indicate what the response contains or any matching behavior (e.g., exact vs. partial match on razao_social), leaving minor gaps.

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 one required string parameter, razao_social, but schema_description_coverage is 0%. The description never mentions or explains this parameter, so the agent must infer meaning from the parameter name alone. The name is fairly self-evident, but the description does not compensate for the lack of schema documentation.

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 a specific action ('consulta') and resource ('Empresas' via SUSEP in an official source), which distinguishes it from the unrelated sibling tools. It could be more precise about exactly which company data is returned, but the core purpose is 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?

The description provides useful context: it uses official sources, requires no platform credentials, and is paid via prepaid credits. However, it gives no explicit guidance on when to choose this tool over alternatives or when not to use it, and sibling tools are not referenced.

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, and openWorldHint=false. The description adds context by specifying exactly what state is returned (MCPs, connection status, accounts, catalog tools), which is sufficient for a read-only inspection tool. 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?

Single, tightly worded sentence that front-loads the purpose and enumerates the return contents. Zero fluff.

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 tool with strong annotations, the description fully explains the output contents. It doesn't describe return format (no output schema), but for this type of tool that is acceptable. Could mention if it returns errors vs state, but minor.

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?

Tool has zero parameters. Schema coverage is 100% (no params to document). Description does all the work by explaining what the return contains, so no parameter semantics 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?

Clearly states what it does: returns toolkit state including installed MCPs, connection status, accounts, and catalog tool counts. Distinguishes from siblings like show_version (version info) and connect (which modifies connections).

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?

Implies usage as a diagnostic/inspection tool for reading state. No explicit when-not guidance, but the description's listing of what it returns makes it evident this is for checking connectivity and account status before using other tools.

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