Tribunal TSE: Doadores e Fornecedores

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

Annotations already indicate idempotence (idempotentHint: true) and non-destructiveness (destructiveHint: false), while the description adds behavioral context about persistence: it explains the difference between a permanent header-based connection and a session-only login, and mentions that calling with no args returns a link. This goes beyond the annotations and clarifies the tool's side effects and usage modes.

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 sentence but packs significant information: context, best practice, alternative, and parameter usage. It is front-loaded with the purpose and remains under 100 words. While slightly dense, it is concise and well-structured.

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 simple tool with one optional parameter and no output schema, the description covers the primary workflows (header config vs. session token vs. link retrieval). It doesn't describe edge cases like error handling or token expiration, but these are less critical for an authentication helper. The description is complete enough for an agent to use 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 input schema has 0% description coverage (no param descriptions), but the tool description compensates by explaining the 'token' parameter: it should be a JWT string and is used when pasted for session-based login. It also implies the parameter is optional since calling with no args is an alternative. This adds meaningful semantic context for the single 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 states the tool's purpose: authenticate the user by logging in and obtaining an access token. It explicitly mentions 'log in in the browser, copy the access token' and provides examples of usage, distinguishing it from siblings like 'connect' or 'toolkit_info' via its specific authentication focus.

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: it recommends adding the token as a header for a permanent connection versus pasting it for a session-only login, and tells the user to call with no args to get the link. This provides clear when-to-use and context, though it doesn't explicitly mention alternatives to this tool.

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 readOnlyHint and idempotentHint annotations, the description discloses meaningful response behavior: authenticated:true, empty pending[], and connect_url/per-install URLs depending on credential state. This is strong behavioral detail for a zero-parameter read-only tool, though it does not cover partial-connection states.

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, no filler, and information is front-loaded: the first sentence states the purpose, the second explains conditional outputs. Every word contributes to understanding.

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 return shape and the key condition branches (all connected vs. missing credentials), which is sufficient for a simple status tool with no input schema and no output schema. It leaves partial-connection behavior unspecified, preventing a perfect score.

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 zero parameters and 100% schema description coverage, the schema already exhaustively documents the input surface. The description adds no parameter-specific meaning, but that is unnecessary; the baseline of 4 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 uses a specific verb ('Returns') and resource ('connection status and URLs'), making the tool's core function unambiguous. It also describes expected response states, clearly distinguishing this status-checking tool from the sibling 'authenticate' tool, which likely performs authentication actions.

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 conditional contexts: use this tool to check all-providers-connected status or to retrieve connect URLs when credentials are missing. It does not explicitly name alternatives or exclusion cases, but the conditions imply the appropriate usage window.

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 minimal annotations (readOnlyHint=false, openWorldHint=true), the description reveals side effects: invoke works even if the MCP is not installed, runs one-off, doesn't bloat the toolkit, and may return connect/checkout links requiring user action and retry. It also notes permission requirements for install/uninstall/subscribe/cancel. No contradictions with 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 long but dense; it front-loads the purpose and then details the core flow, permission rules, and prompts library without fluff. While it could be organized more neatly (e.g., separate paragraphs per concern), every sentence adds substantive information.

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 complexity (23 params, no output schema), the description covers the key flows (search/describe/invoke), authorization, billing redirects, permissions, and the prompt library feature. It lacks some details on actions like resume and the exact interface for report_bug/request_mcp, but overall it is sufficiently complete for a high-level agent to understand and use the 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?

Schema coverage is 0%, so the description must compensate. It explains the action parameter and the core flow, mentioning tool_id/arguments for invoke, and touches on prompt-related actions. However, many parameters (limit, query, mcp_id, conversation, prompt_vars, etc.) are not individually described, leaving gaps in meaning despite the overall flow being documented.

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 the mcp.ai marketplace, with a specific verb ('the way to run them') and scoped resource (in-platform catalog). It distinguishes from siblings like authenticate/connect by framing marketplace as the discovery/execution layer, and enumerates distinct action verbs (search, describe, invoke, install, etc.).

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?

Explicit when-to-use guidance is abundant: 'prefer invoke for a single/occasional use' vs 'use install only to make an MCP PERMANENT', and the flow 'search → describe → invoke' is spelled out. It also gives exclusion criteria, e.g., 'list_tools lists what is callable right now', and states write operations require workspace owner/admin.

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 readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description does not contradict these, but it also doesn't add much beyond what annotations provide. It mentions including conversation for reproduction, which is a behavioral detail, but doesn't disclose any side effects, auth requirements, or rate limits. Since annotations cover some safety profile, a 3 is appropriate.

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, two sentences, and front-loaded with the purpose. It includes a key instruction about including the conversation array. No wasted words, but it could be slightly more structured with parameter details.

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 has 3 parameters, no output schema, and no schema descriptions, the description is insufficient. It doesn't explain the 'context' parameter, the format of 'conversation' (though it says array, the schema type is string), or what happens after reporting. For a feedback tool, it might be acceptable, but the lack of parameter semantics and behavioral details makes it incomplete.

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. The description mentions 'conversation array' but the schema has a 'conversation' parameter as a string with default '[]'. It doesn't explain the 'context' parameter at all, and 'message' is obvious. The description adds minimal value beyond the schema, leaving 'context' and the format of 'conversation' unclear.

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 specific verbs and resources, and it distinguishes from siblings by focusing on reporting issues rather than authentication, connection, or marketplace functions. However, it doesn't explicitly differentiate from potential similar tools, but given the sibling list, it's clear enough.

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 it (when reporting bugs, missing features, or feedback) but does not provide explicit guidance on when not to use it or alternatives. It mentions including the conversation array for reproduction, which gives some context, but lacks exclusions or comparison to other 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, idempotentHint, and destructiveHint false, establishing the safety profile. The description adds a 'current' snapshot qualifier, but no further behavioral context beyond what annotations provide.

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 of eight words, front-loaded with the verb and object, containing no filler or redundant detail.

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, idempotent version-checking tool with annotations covering safety, the description fully communicates the tool's purpose. No output schema is present, but the expected return (version strings) is naturally implied.

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 zero parameters, the schema is complete, and the baseline per the rubric is 4. The description does not need to explain parameter syntax or semantics, as there are none.

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?

Description uses a specific verb 'Show' and resource 'current MCP platform and adapter versions', making its function unambiguous. It clearly distinguishes from sibling tools like marketplace or report_bug, which serve different purposes.

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 when-to-use or alternative guidance is provided, but the tool's purpose is self-evident for retrieving version information. Usage context is implied by the tool's name and description.

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, so the safety profile is covered. The description adds value by specifying exactly what state is returned, which is especially important because no output schema exists.

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, well-structured sentence front-loads the purpose and packs in the key output categories without wasted words. Every clause adds meaningful information.

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 low complexity, zero parameters, strong annotations, and absence of an output schema, the description fully conveys what the agent can expect. It enumerates all major result components: installed MCPs, statuses, accounts, and tool counts.

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 accepts zero parameters and the schema is empty, so there is no parameter semantic burden. Per the rubric, zero-parameter tools receive a baseline 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 ('Returns') and names the exact resource ('current toolkit state') with enumerated contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly differentiates it from action-oriented siblings like connect and authenticate.

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 makes the informational, read-only nature clear, implying it is for inspecting state rather than performing actions. It does not explicitly name alternatives or exclusions, but the context of sibling tools (connect, authenticate, marketplace) makes the appropriate usage obvious.

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 valuable context: data is non-confidential (não é dado sigiloso), the client is the data controller under LGPD, and it's a paid per-query service. There is no contradiction with 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 block of three sentences, front-loaded with purpose. It is concise and includes legal and payment details, but some of this context might be better placed in platform-level documentation. Still, it avoids redundancy and is easy 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?

The description covers the tool's purpose, legal obligations, and payment model, but lacks parameter semantics and expected output. With no output schema, the agent is left without clarity on what data is returned. It is sufficient for basic usage but not fully complete for a complex consultation 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?

Schema description coverage is 0%, and the description does not explain any parameter. Although parameter names (ano, cpf, cnpj, nome) are self-explanatory, the description fails to add meaning like formats, required combinations, or how they interact. With low coverage, this is a significant gap.

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 'Tribunal TSE: Doadores e Fornecedores, consulta em fonte oficial' – a specific verb (consulta) and resource (Doadores e Fornecedores from TSE). This distinguishes it from sibling tools like 'authenticate' and 'marketplace', which serve entirely different purposes.

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 'consulta em fonte oficial' and that it's 'a mesma disponível ao cidadão', implying legitimate queries. It also notes payment and LGPD compliance, but does not explicitly state when to use this tool over alternatives. Since siblings are unrelated, the lack of explicit exclusions is acceptable.

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