Portal da Transparência: Seguro Defeso

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

Annotations indicate this is not read-only, not destructive, and idempotent. The description adds context about what happens: it generates a login link or accepts a token, and mentions the permanent vs session-only distinction, which is useful. It doesn't contradict annotations. It could add details about session expiry or security, but the disclosure is adequate.

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 paragraph with clear sentences, but it is lengthy and combines multiple instructions. It is front-loaded with the target audience and action. Could be split into clearer steps, but it is reasonably concise given the complexity.

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 main usage scenarios: obtaining a token via browser, permanent configuration, and session-only use. It doesn't describe return values (no output schema), but the tool's purpose is simple. It could mention error cases or token update, but for a straightforward authentication tool, it is sufficiently 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 has one optional parameter 'token' with no description (0% coverage). The description compensates by explaining that 'token' is a JWT to be passed for session-only login, and that calling with no args returns a link. This provides meaningful semantics beyond the bare 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 explains the tool's function: to authenticate an IDE agent by obtaining and applying an access token. It distinguishes between permanent config-based and session-based login methods. However, it is a bit verbose and could be more concise.

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 explicitly states when to use the tool: to log in, and provides two usage paths (permanent via config header, session-only via token argument or no args to get link). It implicitly contrasts with alternatives like 'connect' and 'portal_transparencia...', though not explicitly naming them. It also gives clear step-by-step 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, idempotentHint, and destructiveHint, but the description adds meaningful behavioral detail about the two possible response states (authenticated:true vs connect_url). This goes beyond the structured annotations by explaining under what conditions each state is returned.

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 fluff. The first sentence states the core function, the second explains edge cases. Every sentence adds value, and the information 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 status-check tool with no parameters, annotations, and no output schema, the description is fully sufficient. It explains both possible outcomes and the URLs returned, leaving no ambiguity about the tool's behavior.

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% (empty schema). Per the rubric, 0 parameters warrants a baseline of 4. The description does not need to explain parameter usage, and it doesn't introduce any confusion.

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 it 'Returns connection status and URLs', specifying the resource and action. It also distinguishes itself from siblings like 'authenticate' by focusing on status retrieval rather than initiation. The two conditional outcomes are explicitly described, 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?

The description implies usage for checking connection status but does not explicitly state when to use this tool vs alternatives like 'authenticate'. No when-not-to-use guidance is provided, so usage context remains implicit 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?

Beyond the annotations, the description discloses that writes require workspace owner/admin, invoke runs one-off without bloating the toolkit, and auth/payment failures surface as connect/checkout links. It also notes that search/describe flag installed status and prompt links open without login. No contradiction with 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 dense but well-structured: it front-loads the core flow, then the key invoke behavior, the install-vs-invoke distinction, remaining actions, and the prompt library. Every sentence adds information, though a single long paragraph with no bullets makes it slightly harder 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 14-action tool with no output schema, the description covers the main flows, auth requirements, billing behavior, and prompt library. It omits details on return formats and several less-central parameters, but the core selection and invocation path is well 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?

With 0% schema description coverage, the description compensates by explaining the central `action` enum and the core flow (query → mcp_id → tool_id → arguments), plus prompt-related params like prompt_vars, prompt_slug, and prompt_body. However, many of the 23 parameters (limit, immediate, tier_slug, conversation, cancel_reason, etc.) remain unexplained, so it does not fully cover 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 opens with 'official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them' and then lays out the search→describe→invoke core flow. It clearly distinguishes this tool from siblings like authenticate, connect, and toolkit_info by positioning it as the catalog-and-execution hub.

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 when-to-use 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 'request_mcp asks us to build a NEW MCP when nothing fits'. It also explains what to do when invoke returns a connect or checkout link.

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?

Adds meaningful behavioral context beyond the readOnly/idempotent annotations: the data is public (same as available to citizens), non-confidential ('não é dado sigiloso'), requires no platform credentials, but incurs per-query charges against prepaid credit, and the client bears LGPD controller responsibility. This enriches the safe-read picture with a concrete cost implication an agent must surface before invoking. Slightly marred by the ambiguous 'sem credenciais da plataforma' phrasing, but clearly value-adding.

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?

Three sentences that front-load the core purpose, but include a redundant construction ('Hospedado pela plataforma, sem credenciais da plataforma') that repeats 'plataforma' and creates ambiguity, plus LGPD legalese that is defensible but boilerplate. The functional content could be tightened while retaining the payment and legal caveats.

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 4-parameter tool with no output schema and zero parameter documentation, the description covers the domain, data sensitivity, cost model, and legal responsibility well, but omits response/return expectations, parameter combinations, and failure behaviors (e.g., insufficient credit, invalid CPF). The LGPD and payment context are valuable additions, but the lack of parameter and output guidance leaves gaps the agent must guess at.

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 does not compensate: it never clarifies cpf, nis, data_inicio, or data_fim formats, whether CPF and NIS are alternatives or complementary, or whether date fields form a required range. An agent is left to infer meaning purely from parameter names and domain knowledge. Since coverage is below 50%, the description was obligated to compensate and did not.

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's purpose: querying Seguro Defeso data from the official Transparency Portal ('Portal da Transparência: Seguro Defeso, consulta em fonte oficial'), establishing a specific verb+resource+scope. It stops short of explicitly distinguishing itself from siblings, though the sibling set (authenticate, marketplace, connect) makes the query role evident by contrast. Core function is clear but somewhat diluted by business/compliance boilerplate.

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 conveys when the tool is safe/appropriate to use through operational context: no platform credentials required, pay-per-query with prepaid credit, and the public (non-confidential) nature of the data. However, it names no alternatives or exclusions (e.g., 'for X, use Y'), nor does it advise on scenarios this tool should NOT be used for. Usage context is implied rather than explicitly contrasted with 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 indicate idempotentHint true and destructiveHint false, so safety profile is covered. The description adds behavioral context by instructing to include the conversation array for reproduction, which is beyond the raw schema. 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?

Two sentences, front-loaded with purpose, no redundant wording. Every detail 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 bug-report tool with 3 params and no output schema, the description covers the main action and key parameter. Lack of return-value info is acceptable given no output schema. Sibling tools are unrelated, so no confusion.

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 for parameters. It explains the 'conversation' parameter's role (reproduction), but does not clarify 'message' or 'context'. However, 'message' is self-evident from the verb 'report', and 'context' is a generic optional string. This is adequate but not rich.

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 'Report' and clearly identifies the resource: bugs, missing features, or feedback. This distinguishes it from all sibling tools, which cover authentication, connectivity, marketplace, portal queries, version, and 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 clearly implies when to use the tool: when encountering a bug or wanting to provide feedback. It does not explicitly exclude alternatives or state when not to use it, but siblings are obviously unrelated, so context is clear.

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 only that versions are 'current' and specific to platform and adapter, without additional behavioral detail like return format or side effects; it does not contradict 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?

A single, front-loaded sentence states exactly what the tool does with no filler. It is appropriately sized for a zero-parameter utility.

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, zero-parameter read-only version query with robust annotations, the description is sufficient. No output schema exists, but the return value (version identifiers) is self-evident from the purpose, and no additional caveats or prerequisites are needed.

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 is complete by default (100% coverage). The description therefore has no parameter semantics to add, warranting the baseline score of 4.

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 exact resource ('current MCP platform and adapter versions'), making the tool's function unambiguous. It clearly differs from sibling tools like authenticate, connect, or marketplace by targeting version inspection.

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 does not explicitly state when to use this tool vs alternatives or any exclusions. Usage is implied by the purpose—when version information is needed—but there is no direct guidance on context or alternative 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is well-covered. The description adds value by specifying what state is returned and its composition, but it does not add details like authentication prerequisites or potential latency.

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 purpose and lists the key output categories without any fluff. Every word contributes to clarity.

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 status tool with zero parameters, no output schema, and comprehensive annotations, the description is complete enough. It specifies all key aspects of the returned state. It could mention the return format (e.g., structured JSON) but that is not a major gap given the tool's simplicity.

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 parameters, so the description carries no burden. The high schema coverage (100%) means there is nothing to add. The description effectively communicates that the tool takes no inputs, and the tool's output covers a specific set of information, making parameter semantics 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 the current toolkit state, enumerating specific types of information (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from sibling tools like authenticate, connect, and marketplace, which focus on different operations.

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 as a status/inspection tool, but it does not explicitly state when to use it versus alternatives (e.g., show_version for version info, connect for managing connections). It provides the context of returning state, but lacks explicit when/when-not guidance.

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