Tribunal TRT20: Consulta Processual

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

The description adds behavioral context beyond annotations: it explains the two login modes (permanent via header vs session-only via token), how to trigger the login link, and the distinction of token expiry. Annotations already indicate idempotency and non-read-only, and the description aligns with these while adding meaningful workflow details.

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 but well-structured, front-loaded with the tool's purpose, then delineating two clear usage paths. Every sentence contributes value, though it could be slightly more streamlined for scanning.

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 lack of an output schema, the description covers the essential flow: how to initiate login, the two authentication methods, and token persistence. It does not detail return values or error cases, but for an auth tool this is adequate and approachable.

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 schema description coverage at 0%, the description fully compensates by explaining the 'token' parameter: it is an optional JWT used for session-only login, and calling with no args returns the login link. This provides complete parameter 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 states the tool's purpose: authenticate the MCP.AI server for IDE agents via a browser login and token exchange. It specifies the resource (auth for MCP.AI) and distinguishes itself from siblings by detailing a unique token-based flow involving config header or session token. This is a specific verb+resource+scope.

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 usage context: when to use the permanent config-header method versus the session-only token method, and how to call with or without the token. It does not explicitly compare against the sibling 'connect' tool, but the guidance is clear enough for an agent to know when to use 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?

Annotations already indicate read-only and non-destructive behavior. The description adds useful behavioral detail beyond annotations by specifying exactly what happens when all providers are connected versus when credentials are missing, including the exact fields returned (authenticated, pending[], connect_url).

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, front-loaded with the primary purpose, and each sentence contributes meaningful information. It explains the two possible states clearly without unnecessary words.

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 no input parameters and no output schema, the description sufficiently covers the tool's behavior and expected return information. The two-state explanation is complete enough for an agent to know what to expect and when.

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 the schema coverage is 100%, so there are no parameter semantics to clarify. The baseline for zero-parameter tools is 4, and the description appropriately focuses on behavior rather than input.

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 a specific verb and resource. It goes beyond a simple label by explaining the return conditions, which distinguishes it from sibling tools like 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 provides clear context for when to use this tool: to inspect connection status and retrieve URLs when credentials are missing. However, it does not explicitly mention alternatives or state when not to use it, such as contrasting with authenticate.

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?

Provides rich behavioral detail far beyond the sparse annotations (readOnlyHint: false, openWorldHint: true): 'invoke works even when the MCP is NOT installed — it runs the tool pontualmente (one-off), without adding the MCP to the toolkit and without bloating the tool list.' It discloses conditional auth flows ('if the MCP needs a credential/login, invoke returns a connect link'), payment edge cases ('if it is paid and the wallet is empty, invoke returns a checkout/top-up link'), and permission requirements for writes. 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?

A ~290-word wall of text in a single unbroken paragraph with no lists, headers, or bolding. While the first sentence is strong and front-loaded, the mid-paragraph 'KEY:' and 'Writes (...)' parentheticals add parse burden. Mixed-language content ('pontualmente') and quoted strings further reduce scannability. The content is valuable but desperately needs bullets or sentence-per-line structure to match the adjacent rubric examples.

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, 23 parameters, no output schema, and no parameter descriptions, the coverage is strong: the full lifecycle (search→describe→invoke), billing/subscription behavior, the prompt library subsystem, and operator permission model are all explained. Gaps exist (resume action semantics, error conditions, idempotency), but given the complexity, the description is nearly exhaustive in scope.

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 coverage across 23 parameters, the description correctly bears the meaning burden and covers much ground: it explains action enum values (search, describe, install, invoke, list_tools, subscribe, cancel, report_bug, request_mcp, search_prompts, get_prompt, publish_prompt), the tool_id→invoke relationship, and the prompt library parameters (prompt_slug, prompt_body, prompt_vars). However, several parameters (immediate, resume, conversation, cancel_reason) are never mentioned, leaving gaps in an already-parameter-heavy 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 opens with 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' immediately establishing a specific verb+resource. It names concrete capability requests ('find an MCP that does X', 'consulta um CPF') and lays out the core search→describe→invoke flow. It clearly differentiates from all siblings (authenticate, connect, report_bug, show_version, toolkit_info, tribunal_trt20_processo_consultar), none of which overlap with marketplace/catalog/execution functionality.

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?

Excellent explicit when/when-not guidance: 'Use install only to make an MCP PERMANENT in the active toolkit... prefer invoke for a single/occasional use' and 'list_tools lists what is callable right now.' It even explains the search discovery path, the fallback behavior (connect link, checkout link), and distinguishes MCPs from the PROMPT LIBRARY ('which is about ready-made prompt TEXT rather than MCPs'), giving a full decision tree.

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 provide readOnlyHint=false and idempotentHint=true, but the description adds limited behavioral context. It instructs to include the conversation array for reproduction, but doesn't describe the outcome, side effects, or any additional context beyond what annotations already convey.

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, with two clear sentences that efficiently convey the tool's purpose and a key usage instruction. No unnecessary words or redundancy.

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 is adequate for a simple bug-reporting tool. It covers what to do and mentions the conversation array, but lacks details about output, authentication requirements, or post-submission behavior. Given the tool's low complexity, this is acceptable but not exhaustive.

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 description explains the 'conversation' parameter (for reproduction) but does not clarify the 'message' or 'context' parameters. Schema coverage is 0%, and the description only partially compensates, leaving two of three parameters undefined.

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: reporting a bug, missing feature, or feedback. It also distinguishes itself from sibling tools (authenticate, connect, marketplace, etc.) by focusing on issue reporting.

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 implies when to use (when encountering a bug, missing feature, or needing to send feedback) but doesn't explicitly mention when not to use or compare alternatives. The context is clear enough for most scenarios.

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 the scope of what versions are shown but does not disclose return format or other behavioral details; 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, front-loaded sentence with no filler or redundancy. Every word contributes to conveying the tool's 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 zero-parameter, read-only version query with strong annotations, the description is complete: it names exactly what information is returned. The absence of an output schema is acceptable 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 tool has zero parameters and an empty schema, so the baseline of 4 applies. The description correctly adds no parameter-specific details because none are 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?

Description uses a specific verb ('show') and names the exact resource ('current MCP platform and adapter versions'), making the tool's purpose unmistakable. It clearly distinguishes from sibling tools like authenticate or report_bug.

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 guidance is provided on when to use this tool versus alternatives such as toolkit_info, and there are no exclusions or prerequisites. The only implied context is needing version information, but no explicit usage direction is given.

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, so the safety profile is known. The description adds value by detailing the return content (connection status, accounts, catalog counts), which is behavioral context beyond the annotations. No contradictions detected.

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, well-structured sentence that leads with the action verb ('Returns') and then provides a clear, comma-separated list of what is included. Every word adds value, and it is easily scannable.

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 tool with no parameters and no output schema, the description is complete: it states the tool returns the toolkit state and enumerates all components. It does not explain the output format, but for a state-inspection tool this is sufficient, especially with supportive annotations.

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 takes zero parameters, so there is no parameter schema to supplement. The baseline of 4 applies because the description need not explain parameter meanings; it correctly focuses on the output.

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 ('current toolkit state'), then enumerates exactly what is included: installed MCPs, connection status, accounts, and catalog tool counts. This clearly distinguishes it from siblings like 'show_version' and leaves no ambiguity about the tool's function.

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 guidance is provided about when to use this tool versus alternatives (e.g., show_version). The usage is implied from the purpose: if you need toolkit state, this is the tool. There are no exclusions or alternative references, so it falls short of a 4 but is above having no 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?

Beyond the readOnly, idempotent, and non-destructive annotations, the description adds valuable context: payment via prepaid credit, no platform credentials required, data is non-confidential and identical to what citizens can access, and LGPD responsibility. This enriches the behavioral understanding 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 paragraph with multiple sentences covering purpose, hosting, payment, legal aspects. While not excessively long, it is not front-loaded and includes legal disclaimers that could be streamlined. It is acceptable but could be more 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?

The description covers purpose, payment, and legal context, but lacks parameter explanations and any details about return values (though no output schema exists). For a simple 2-parameter tool, it is moderately complete but leaves gaps in parameter semantics.

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 description does not explain either parameter (grau or numero_processo). With 0% schema coverage, it should compensate by describing their purpose or format, but it fails to do so. The only hint is the tool name itself, which is insufficient.

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 is a consultation tool for TRT20 court processes, specifying the verb 'consultar' and the resource 'processo' from an official source. It distinguishes itself from sibling tools which are generic platform utilities like authenticate 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 provides context on how to use the tool (prepaid credit, no platform credentials) but does not explicitly state when to use it versus alternatives or when not to use it. Siblings are unrelated, so no direct comparison is needed, but explicit usage guidance is missing.

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