Tribunal TRT12: Consulta Processual

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

Annotations indicate idempotentHint: true, meaning the tool is safe to call multiple times. The description adds context by explaining the browser-based flow and the token handling, including that providing no args yields a link. However, it does not explicitly mention that the token is a JWT or discuss expiration, but the annotation already handles idempotency. Overall, the description adds value beyond annotations by clarifying the authentication flow.

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 and well-structured, with a front-loaded statement about the tool's purpose and then actionable instructions. It covers two use cases in a single sentence, and the recommendations are clear. No wasted 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's simplicity (one optional parameter, no output schema), the description is highly complete. It explains both invocation modes, the permanent setup via header, and references the browser flow. It leaves no gaps for an agent to misunderstand how to 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?

The schema only defines 'token' as a string with no description. The tool description compensates by explaining the token's purpose: it is a JWT access token that the user pastes, and that calling with { token: ... } enables session-only login. It also mentions that the token can be used as a header for permanent connections. This adds significant semantic meaning beyond the schema's minimal definition.

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: to authenticate with MCP.AI, either by providing a token after browser login or triggering a login link. It specifies the verb 'authenticate' and the resource (MCP.AI) it interacts with, making it distinct from sibling tools like 'connect', 'marketplace', 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?

The description explicitly explains when to use this tool: when an IDE agent needs to authenticate. It also distinguishes two usage scenarios: passing a token for session-only login, or calling with no args to get a login link. It further recommends a permanent solution by adding an Authorization header to the server config. This is clear guidance on how to use the 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral detail about the two possible states (all connected vs. missing credentials) and what the response contains. It does not contradict annotations. It adds some value beyond annotations, but not extensive behavioral context like rate limits or 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 two sentences, front-loaded with the main purpose, and provides concrete details about the response states. Every sentence adds value, and there is no 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?

Given the tool has no parameters, no output schema, and annotations cover safety, the description is complete enough. It explains the two possible outcomes and what URLs are returned. It could mention the format of URLs or the meaning of 'pending' array, but for a simple status tool, it is 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?

The tool has zero parameters, and schema description coverage is 100% (vacuously). The description does not need to explain parameters. It explains the output semantics, which is the main value. Since there are no parameters, a 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 clearly states the tool returns connection status and URLs, and distinguishes between the all-connected state and missing-credentials state. It is specific about the resource (connection status) and the output (authenticated flag, pending array, connect URLs). It does not explicitly differentiate from siblings, but the purpose is clear.

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 this tool: to check connection status and get URLs when credentials are missing. However, it does not explicitly state when not to use it or mention alternatives like 'authenticate' or 'toolkit_info'. The context is clear but lacks explicit guidance on choosing between this and related 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?

The description discloses critical behavioral details beyond annotations: invoke works even without installation, returns connect/checkout links for auth/payment, writes require owner/admin, and search/describe flag installed status. It also notes the one-off install behind invoke. This adds substantial context about side effects and permissions, aligning with annotations (readOnlyHint=false, destructiveHint=false) without contradiction.

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 information-dense, organized around the core flow and sub-actions. It avoids redundancy and front-loads the main use case. While it could benefit from bullet points for readability, every sentence contributes value, making it appropriately sized for the tool's 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?

Given the tool's complexity (23 params, 14 actions, no output schema), the description is quite complete. It covers the primary flow, permissions, auth/payment handling, and the prompt library. Some actions (resume, cancel) are only mentioned, and return formats are not detailed, but the overall picture is clear enough for an agent to select appropriate actions. It lacks explicit return descriptions but that is partially mitigated by the action-specific explanations.

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 compensate. It explains the meaning of key parameters implicitly (action values, mcp_id, tool_id, arguments, query/limit for search) and the prompt library params (prompt_vars, prompt_slug). However, it does not detail every parameter (e.g., immediate, tier_slug, prompt_targets, cancel_reason), leaving some gaps. Still, it adds significant meaning beyond the bare parameter names, meeting the baseline of 4 for zero coverage.

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 official mcp.ai marketplace, describing its dual role as catalog and execution engine. It specifies the core actions (search, describe, invoke) and distinguishes itself from siblings like authenticate, connect, and report_bug, which are separate tools. The verb+resource structure is precise.

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 guidance on when to use invoke vs install: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT in the active toolkit'. It also explains when to use subscribe/cancel, request_mcp, and the prompt library actions. Alternatives and context are clearly provided.

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=false and destructiveHint=false, covering safety expectations. The description adds the behavioral nuance that the conversation array is used for reproduction, but doesn't disclose side effects like ticket creation or data storage. With annotations present, this is acceptable but not rich.

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 purpose and a critical usage instruction. No filler or redundant content.

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 reporting tool with 3 parameters and no output schema, the description covers the core action and a key usage detail (conversation for reproduction). It's missing explanation of the 'context' parameter, but overall the tool is straightforward and the provided info is sufficient for most use cases.

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 explains the purpose of the 'conversation' parameter ('Include the conversation array with recent messages for reproduction') and implies 'message' is the report text. However, 'context' remains unexplained, and the overall parameter guidance is minimal.

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 'Report a bug, missing feature, or send feedback'—a specific verb and resource that distinguishes this from siblings like authenticate or marketplace. The purpose is immediate and 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 provides clear context—this is the tool for bug/feature/feedback reports. It also instructs to include the conversation array for reproduction. However, it doesn't explicitly contrast with alternatives, but no sibling tool serves a similar purpose, so this is sufficient.

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 the tool as read-only and non-destructive. The description adds that it returns both platform and adapter versions, providing clarity on the exact data returned without contradicting 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 a single, concise sentence that directly conveys the tool's purpose without any redundant or extraneous content.

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 absence of parameters and output schema, the description sufficiently explains what the tool does. It does not specify the return format, but for a simple version check, this is not essential.

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 no parameters, so the schema is fully covered. The description implies that no input is needed, which aligns with the empty parameters list. 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 clearly states the tool shows the current MCP platform and adapter versions, using a specific verb ('show') and resource ('versions'). It distinguishes from siblings like 'toolkit_info' which likely provides broader information, and 'authenticate'/'connect' 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?

While no explicit alternative comparison is given, the simplicity and specificity of the tool make its use case obvious: when version information is needed. Sibling tools like 'authenticate' and 'connect' clearly have different roles, so no confusion arises.

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, covering the safety profile. The description adds behavioral detail about what information is returned (installed MCPs, status, accounts, tool counts), which complements the annotations. No contradiction exists, and the description enriches the agent's understanding of the tool's output without contradicting 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, well-structured sentence that front-loads the core purpose ('Returns the current toolkit state') and then lists the key details. There is no fluff or repetition, and every part of the sentence adds value. This is exemplary conciseness and structure.

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 simplicity (no parameters, no output schema, no complex behavior), the description fully covers what it does and what it returns. It lists the specific components of the state it reports, making it complete for an agent to decide when to call it. No additional context is 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, and the schema coverage is 100% (trivially, since there are no properties). Per the rubric, a baseline of 4 applies for 0-parameter tools. The description does not need to explain parameters, and it doesn't add any confusing parameter information. It remains clear and avoids redundancy.

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 function: 'Returns the current toolkit state' and enumerates the specific aspects covered (installed MCPs, connection status, accounts, catalog tool counts). This is a specific verb+resource and distinguishes it from sibling tools like 'connect' or 'authenticate' which perform actions, whereas this tool is purely informational.

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 context (for inspecting toolkit status) but does not explicitly state when to use it versus alternatives or provide exclusions. It gives clear context by saying it returns the current state, making it obvious it's for assessment, but it lacks explicit 'when to use' or 'when not to use' guidance that would earn a 5.

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 genuine value beyond this by disclosing the payment model (prepaid credits per consultation), absence of platform credentials, and the public/non-secret nature of the data plus LGPD compliance responsibilities. No contradiction with annotations 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?

The description front-loads the core purpose in its opening phrase, which is good, but roughly a third of the paragraph is LGPD/compliance boilerplate (data controller responsibilities) that does nothing to guide tool invocation. It is one dense paragraph that could say the same in fewer 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?

With no output schema present, the description should explain what data the tool returns — it does not. It also leaves the 'grau' parameter unexplained. The tool is simple (2 params, 1 required) and annotations cover safety, so it is not severely incomplete, but the return semantics are a notable gap for an agent deciding how to use results.

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 parameter explanations — it does not. 'numero_processo' is inferable from the tool name, but the optional 'grau' parameter (judicial instance/degree) is never explained anywhere, leaving the agent to guess its meaning or valid values.

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 verb+resource: 'Consulta Processual' (procedural consultation) for TRT12, querying official Brazilian court sources. It distinguishes itself from all sibling tools, which are platform utilities (authenticate, connect, marketplace, report_bug, etc.). Slight deduction for mixing compliance/admin context with the core purpose, though the first phrase 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 some usage context — it is hosted by the platform with a pay-per-query prepaid-credit model, requires no platform credentials, and accesses public (non-confidential) data. However, it never explicitly states when to use this tool versus alternatives or gives any exclusion criteria; the 'when' is only implied by the tool's nature as a court query.

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