Tribunal TRT9: Consulta Processual

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

Annotations indicate idempotentHint=true and destructiveHint=false, which the description does not contradict. The description adds behavioral context beyond annotations: it explains that the tool opens a browser for login, returns a link when called with no args, and that the token can be used for a permanent or session-only connection. It also notes the token is a JWT. This adds value beyond the annotations, though it doesn't detail side effects like browser opening or token storage.

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 is well-structured and front-loaded with the purpose. It is concise, covering the key usage modes without excessive detail. The sentences are efficient, though the structure could be improved with bullet points or clearer separation of the two usage modes. Overall, it earns its place with 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?

Given the tool's simplicity (one optional parameter, no output schema), the description is fairly complete. It explains the two usage modes, the best practice, and the session-only alternative. It doesn't mention error cases or what happens after authentication, but for a simple auth tool with no output schema, this is adequate. The description covers the essential context 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 schema has one optional parameter 'token' with no description, and schema description coverage is 0%. The description compensates by explaining that the token is a JWT and that it can be passed as { token: "<jwt>" } for session-only login. It also clarifies that calling with no args returns the login link. This adds meaning beyond the bare schema, though it doesn't specify the token's format or length in detail.

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 the user by logging in via browser and obtaining an access token. It distinguishes itself from siblings by focusing on authentication, while siblings like 'connect' and 'marketplace' serve different functions. The verb 'authenticate' plus the explanation of login and token acquisition makes the purpose specific and 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 provides explicit usage guidance: it explains two ways to use the tool (permanent config-based token vs. session-only token), and specifies when to call with a token argument versus no arguments. It also gives a best-practice recommendation (adding to config as a header) and mentions the alternative of pasting a token for session-only login. This is clear and actionable.

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, and the description adds meaningful state-specific context: it reveals that the response shape varies based on connection state, including authenticated, pending, and connect_url fields. This goes beyond the basic safety profile provided by 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 compact and front-loaded, with two sentences that each carry useful information. It avoids repetition and clearly explains the primary purpose and conditional outcomes without 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 (no parameters, no output schema) and the strong annotations, the description covers all necessary context: what the tool returns, when each return variant applies, and what the key fields mean. It is complete for an AI agent to invoke and interpret results 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 tool has zero parameters and schema coverage is 100%, so there is no parameter information missing. The description focuses on the return behavior, which is the only meaningful semantic content for a no-parameter tool, matching the baseline for 0 params.

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 connection status and URLs.' It specifies the two possible outcomes (fully connected vs. missing credentials), which distinguishes it from siblings like authenticate by focusing on status reporting rather than performing authentication.

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 conditional behavior ('When all providers are connected... When credentials are missing...') which implies when to inspect this tool's results, but it does not explicitly state when to use connect versus alternatives like authenticate. Usage context is implied 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?

The description discloses many behavioral traits beyond annotations: invoke works even when the MCP is not installed, runs one-off without bloating the toolkit, returns connect/checkout links for auth/payment, and writes require owner/admin. It also notes that search/describe flag installation status. Annotations are sparse (readOnlyHint false, openWorldHint true, etc.), so the description carries the burden and does so thoroughly.

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 dense paragraph of over 500 words. While it front-loads the core flow ('Core flow: action=search...'), it lacks formatting, breaks, or bullet points. It covers many actions and context, but every sentence doesn't earn its place—some details (e.g., prompt library) could be condensed. It's comprehensive but not concise or well-structured for quick 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?

For a tool with 23 parameters, 14 actions, and no output schema, the description covers the main flow, edge cases (auth, payment), and the prompt library. However, it omits details on some actions like 'resume' (in enum but not explained), and parameters like 'immediate', 'tier_slug', 'conversation' are unexplained. It also doesn't specify parameter formats or return structures. While it's strong for the primary use cases, it's incomplete for full tool mastery, warranting a middle 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?

Schema coverage is 0%, so the description must compensate. It explains the key parameter 'action' by listing all its enum values and their purposes (search, describe, install, invoke, etc.). It also explains parameters like mcp_id, tool_id, arguments implicitly through the flow, and covers prompt-related parameters (prompt_body, prompt_slug, prompt_vars, prompt_title, etc.) for the prompt library. However, not all 23 parameters are explicitly described (e.g., limit, query, message, immediate, tier_slug, conversation, report_context), but the action enum covers most core semantics. This is strong compensation for a complex 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: 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It distinguishes itself from siblings by explaining its unique role (search, describe, invoke, install, prompt library) and names sibling tools like authenticate, connect, and tribunal_trt9_processo_consultar. The core flow is explicitly described, 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 gives explicit guidance on when to use each action: 'Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile... → invoke RUNS that tool.' It also clarifies when to prefer invoke over install: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT in the active toolkit.' It covers prompt library usage and notes write actions require owner/admin. This is comprehensive guidance with clear 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 declare the tool is idempotent and non-destructive; the description adds that conversation data is used for reproduction. However, it doesn't disclose actual side effects such as sending data or response behavior, beyond what the annotations imply.

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 with front-loaded main action, no redundant wording. Every word 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 feedback tool with no output schema, the description covers the purpose and key parameter but omits explanation of the optional 'context' parameter and any return/response behavior, leaving some gaps for an agent.

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 no parameter descriptions (0% coverage). The description clarifies the 'conversation' parameter's purpose and implies 'message' content, but leaves 'context' undefined, providing only partial compensation.

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 states 'Report a bug, missing feature, or send feedback' with a specific verb and resource, clearly distinguishing it from sibling tools 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 second sentence instructs to include the conversation array for reproduction, providing clear usage context. There are no ambiguous alternatives among the siblings, but no explicit when-not guidance 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 readOnly, idempotent, and non-destructive behavior. The description adds no extra behavioral details beyond the basic action, but it is consistent with the annotations, so no contradiction. Given the annotated safety profile, a score of 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 a single, short, and direct sentence with no unnecessary words or fluff. It is well-structured and immediately comprehensible.

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 parameters and no output schema, the description fully captures the tool's purpose. There is no additional context required for an agent to use it correctly, and the description is 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 tool has zero parameters, and the schema coverage is 100% (empty). Per the rubric, a baseline of 4 is granted for no parameters, and the description does not need to elaborate on parameter semantics since 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?

The description clearly states the tool shows the current MCP platform and adapter versions, which is a specific and unambiguous verb-resource pair. It distinguishes this tool from siblings like 'authenticate' or 'connect' by focusing on version information.

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 purpose makes it obvious when to use it (when you need version info). There is no explicit alternative mentioned, but the simplicity and lack of parameters make the usage context clear. It does not overpromise or confuse.

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 safety profile is clear. The description adds the scope of the returned state but no additional behavioral details such as authentication needs or variability between calls. This is sufficient but not enriched beyond 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 one well-structured sentence that front-loads the main purpose and then lists the specific data returned. Every clause adds meaningful information with no redundancy or filler.

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 informational tool with no output schema, the description fully enumerates what the agent should expect: installed MCPs, connection status, connected accounts, and catalog tool counts. This is sufficient for an agent to select and use the tool 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 tool has zero parameters and schema description coverage is 100%. There are no parameter semantics to compensate for, and the description appropriately focuses entirely on the return content rather than inventing parameter guidance.

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 clearly identifies the resource ('current toolkit state'), enumerating concrete details: installed MCPs, connection status, connected accounts, and catalog tool counts. This distinguishes it from siblings like show_version, which would focus on version 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 implies this is the tool to call when an agent needs an overview of the toolkit's current state, including connections and available catalog counts. It doesn't explicitly state when not to use it or name alternatives, but the context is clear and no competing tool covers this exact purpose.

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 adds substantial context beyond the annotations: the data is official and non-confidential, the platform does not hold credentials, the user pays per query with credit, and the client is legally responsible under LGPD. This explains billing, legal restrictions and data sensitivity.

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 focused paragraph with front-loaded purpose ('Consulta Processual', official source) followed by relevant contextual details. Every sentence contributes meaning, though the LGPD sentence is legal boilerplate and could be shorter.

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 tool's complexity is low and annotations cover the risk profile. Description gives useful behavioral context, but the absence of param explanations is a real gap. The agent would likely need additional information about 'grau' and how the consultation result is returned.

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%. The description does not mention 'numero_processo' or 'grau' at all, leaving the meaning and format of these parameters completely unexplained. The agent has no guidance for filling the required field or the optional degree-level field.

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 immediately identifies a specific resource and action: 'Consulta Processual' via TRT9. It is clearly differentiated from sibling tools like authenticate or marketplace by naming the official court source and the nature of the query.

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 clear context: the tool queries official Brazilian sources, is hosted on the platform, requires no platform credentials, and uses pre-paid credits. It does not explicitly discuss when not to use it or suggest alternatives, but the context is specific enough.

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