Tribunal TRT21: Consulta Processual

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

Annotations already indicate non-read-only, idempotent, non-destructive behavior. The description adds useful context: it explains that calling with no args returns a link, and that token-based login is session-only while config is permanent. It also notes the token is a JWT, going beyond the schema. 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 two sentences, front-loaded with the core purpose and then expanding into usage modes. It's efficient, but slightly verbose with phrases like 'for a permanent, non-expiring connection' that could be trimmed. Still, every sentence 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 one-parameter, optional-arg tool, the description covers the main scenarios (permanent vs session) and invocation patterns. It doesn't describe return values or error handling, but given the simple nature and no output schema, it's adequate. Annotations cover safety, and the description provides enough 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 only defines 'token' as a string with no description. The description fully compensates: it explains the token is an access token from the browser, optional (no args yields a link), and must be a JWT when provided. This adds critical semantic meaning that the schema lacks.

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: authenticating MCP.AI for IDE agents by logging in via browser and obtaining an access token. It explicitly distinguishes the two primary usage modes (permanent config vs. session-only) and contrasts with sibling tools that serve different functions (e.g., connect, marketplace).

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 when-to-use guidance: the 'Best' approach for permanent connections and the alternative for session-only logins. It also explains how to invoke the tool with/without the token parameter. However, it doesn't explicitly mention when to avoid this tool or compare to siblings like 'connect', leaving some implicit.

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 valuable behavioral detail beyond annotations by specifying the exact return shape ('authenticated:true and empty pending[]') and the fallback URL behavior when credentials are missing. 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 two sentences, front-loaded with the core purpose, and every sentence earns its place by explaining a distinct behavioral state. No filler or redundant restatement of the tool name.

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 status tool with no output schema, the description fully covers the return behavior in both relevant states: connected and missing credentials. It also mentions the specific fields returned (authenticated, pending[], connect_url, per-install URLs), making it complete for the tool's complexity.

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 zero parameters and schema description coverage is 100%, so the baseline is 4. The description does not need to explain parameter semantics because there are none to explain.

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', which is a specific verb+resource pairing. It further clarifies the two possible outcomes, making the purpose unambiguous and distinct from siblings 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 clear conditional context: 'When all providers are connected' versus 'When credentials are missing', telling the agent what to expect in each scenario. It does not explicitly name alternatives or exclusions, but the usage context is sufficiently clear for a zero-parameter status 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 annotations, it discloses key behaviors: invoke runs a tool one-off even when not installed without bloating the tool list, credentials trigger a connect link, empty wallet triggers a checkout/top-up link, writes require workspace owner/admin, and installed state is flagged in search/describe. These are substantive operational details that annotations alone would not 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 dense but front-loaded with the marketplace identity and core flow. It uses run-on sentences and a single unbroken paragraph rather than structured bullets, but nearly every clause earns its place given the tool's 14 actions and 23 parameters.

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 complex multi-action tool with no output schema, the description covers the primary workflows, auth/payment edge cases, permission requirements, installed-vs-invoked semantics, and the prompt library. Minor gaps remain: resume and immediate are not explained, and the exact return shapes of several actions are not specified, but overall it is substantially 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?

With 0% schema description coverage, the description must compensate heavily, and it does explain the central action parameter (search/describe/invoke/install/list_tools/etc.). However, several params remain undocumented or ambiguous, including immediate, tier_slug, resume, conversation, prompt_targets, and cancel_reason. Many names are self-explanatory, but the compensation is only partial.

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 is unambiguous: it identifies the tool as the official mcp.ai marketplace, the in-platform catalog of MCPs/tools, and the mechanism to run them. It clearly differentiates itself from siblings by covering the full search/describe/invoke workflow and the prompt library, not just a single 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?

The description gives explicit when-to-use guidance: 'Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile ... → invoke RUNS that tool.' It also directly contrasts invoke vs install ('prefer invoke for a single/occasional use' vs 'Use install only to make an MCP PERMANENT') and points to request_mcp 'when nothing fits.'

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 behavioral context beyond annotations by specifying that the conversation array should be included for reproduction. Annotations already indicate this is a non-read-only operation (readOnlyHint=false) and idempotent, so no contradiction. It doesn't describe post-submission behavior, but that is not critical for a bug-reporting tool.

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 concise sentences, front-loaded with the core purpose and then a key usage instruction. Every word adds value; no fluff or repetition of schema fields.

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 and the presence of annotations, the description covers essential aspects: what it does and what to include. Without an output schema, it doesn't describe return values, but that is not necessary for correct invocation. It is complete enough for an agent to select and call this tool appropriately.

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 coverage at 0%, the description partially compensates by explaining 'message' (the report content) and 'conversation' (to include for reproduction). However, it does not explain the 'context' parameter, and it calls 'conversation' an array while the schema defines it as a string, which could cause minor 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 the tool's purpose with a specific verb ('Report') and resource ('bug, missing feature, or feedback'). It also provides a concrete instruction on what to include (conversation array), making it unmistakable and distinct from sibling tools that deal with authentication, marketplace, or 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 when to use the tool: whenever the user needs to report a bug, missing feature, or send feedback. It also gives usage guidance by instructing to include the conversation array for reproduction. However, it does not explicitly mention when not to use it or alternative tools, though siblings are clearly unrelated.

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 concrete behavioral context—it reports both MCP platform and adapter versions—which is useful 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 a single short sentence that plainly states the action and target. Every word is meaningful, and it is front-loaded with 'Show the current...'.

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 tool with no output schema, the description is fully sufficient. It identifies what the tool returns (platform and adapter versions) without requiring extra explanation.

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 zero parameters, and the rubric sets a baseline of 4 for no-parameter tools. The description adds no parameter 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?

The description clearly states the tool displays 'the current MCP platform and adapter versions,' using a specific verb and resource. This distinguishes it from sibling tools like authenticate or report_bug, and the scope 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?

There is no explicit guidance on when to use this tool versus alternatives, but the name and description imply it is the standard version-check action. This is an implied usage rather than explicit, though for a zero-arg version tool it is fairly 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 indicate read-only, idempotent, non-destructive behavior. The description avoids contradiction and adds useful context by specifying the exact categories of state returned, such as connection status, linked accounts, and exposed catalog tool counts.

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?

One sentence that starts with 'Returns' and immediately itemizes the four relevant aspects of toolkit state. There is no fluff or repetition, and the description is front-loaded with the intent. The apt for a tool with no parameters.

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?

This is a simple zero-parameter, read-only introspection tool with strong annotations and no expected output schema. The description effectively lists the key contents of the response and leaves out non-reinvested details like error handling and side effects.

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 no input schema properties, the description cannot need to clarify parameter behavior; the baseline of 4 applies. The description making the query's purpose self-evident is appropriate and provides enough context for a stateless info call.

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 the tool 'Returns the current toolkit state' and enumerates exactly what that entails: installed MCPs, connection status, connected accounts, and catalog tool counts. This is specific and clearly distinguishes it as an introspection/status tool rather than any of its siblings that perform actions or show other 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 description makes the use case clear: call this when you need an overview of the current toolkit installation and connection state. It doesn't list explicit exclusions or name alternatives, but for a zero-parameter state-retrieval tool the context is sufficiently 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable context: it's hosted by the platform, requires pre-paid credits per query, and clarifies data privacy (LGPD) responsibilities. This goes beyond annotations by explaining the commercial and legal context.

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 three sentences, each adding distinct information: purpose, hosting/payment model, and legal context. It's reasonably concise, though the legal disclaimer could be seen as slightly verbose for a tool description.

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 (2 params, no output schema, no enums), the description covers the purpose and operational context (credits, official source) but lacks parameter semantics and usage examples. It's adequate for a simple query tool but leaves gaps in how to construct the query.

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 the parameters. 'numero_processo' is required but its format (e.g., CNJ standard) is not specified, and 'grau' is optional but its meaning (court level) is not clarified. The description adds no parameter-level detail, leaving the agent to guess.

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: 'Consulta Processual' for Tribunal TRT21, indicating it queries official sources for case information. It distinguishes itself from siblings by specifying the tribunal and the type of query, though it doesn't explicitly contrast with other consultation tools.

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 consulting official Brazilian court data, mentioning it's the same info available to citizens and not confidential. However, it lacks explicit guidance on when to use this tool versus alternatives, and doesn't mention prerequisites like having credits or the required 'numero_processo' format.

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