Tribunal TRT17: Consulta Processual

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

Beyond the annotations, the description explains that a no-arg call returns a login link, that pasting a token gives a session-only login, and that config-header tokens provide a permanent non-expiring connection. This is useful behavioral context beyond the schema and annotations, though it does not describe the exact response payload or error cases.

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 information-dense and every sentence contributes to understanding how to use the tool. It is slightly unstructured, opening with 'MCP.AI for IDE agents (Cursor, etc.)' rather than a clean purpose statement, but it remains reasonably concise for the range of behaviors it describes.

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, one optional parameter, and no output schema, the description is largely sufficient. It covers the main flows: getting a link, passing a token for session login, and the recommended permanent header configuration. It could be more explicit about what happens after a successful token call, but overall it provides enough context for an agent to invoke 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 an optional 'token' string with 0% description coverage, so the description carries the full burden. It clarifies that the token is a JWT, how it should be passed, and that omitting it triggers the login-link flow. This adds meaningful semantics to 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 conveys that this tool handles authentication for the MCP server: the agent should direct the user to log in via browser and copy an access token, then call this tool with that token. It distinguishes from siblings by focusing specifically on the auth flow, though it never explicitly says 'authenticate this server'.

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 concrete usage modes: no args to obtain a login link, or pass { token: '<jwt>' } after the user pastes the token. It also recommends the preferred permanent setup via config header versus the session-only paste route. It does not explicitly discuss when not to use this tool, but it provides clear actionable 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?

Annotations already provide readOnlyHint: true and destructiveHint: false, so the safety profile is known. The description adds meaningful context by explaining the conditional output (authenticated:true with empty pending[] vs. connect_url when credentials are missing). It does not contradict annotations and goes beyond them by detailing the response variations, which helps the agent anticipate results.

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 ('Returns connection status and URLs'), followed by conditional details. Every sentence adds value with no redundancy or fluff. 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 simplicity (no parameters, no output schema), the description covers the main behaviors: it explains the output when all providers are connected and when credentials are missing. However, it does not address partial connection states or define what 'pending' contains, leaving some ambiguity. For a simple tool, this is adequate but could be more thorough.

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, so schema coverage is trivially 100% and the description needs no parameter explanation. Per the rubric, a tool with 0 parameters gets a baseline of 4. The description adds no param-specific info, but none is required. It focuses on output behavior, which 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's function: 'Returns connection status and URLs.' It specifies the verb ('Returns') and the resource (connection status and URLs), and provides conditional outcomes based on connection state. This distinguishes it from sibling tools like 'authenticate' (which performs authentication) and 'show_version' (which shows 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 this tool: when needing connection status and URLs. It describes two scenarios (all providers connected vs. credentials missing) and the associated returns, which gives context for expected behavior. However, it does not explicitly state alternative tools or when NOT to use it, though sibling names like 'authenticate' suggest a complementary role.

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 goes far beyond the minimal annotations (readOnlyHint=false, openWorldHint=true) by disclosing important behaviors: invoke works even when MCP is not installed, runs one-off without bloating the toolkit, returns connect/checkout links for auth/payment, and retries after user action. It also notes permission requirements for writes. 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 a dense but well-organized paragraph that front-loads the core purpose and flow, then systematically covers actions, edge cases (auth/payment), and the prompt library. It is lengthy, but given the tool's complexity (14 actions, 23 params), every sentence contributes value. A bulleted breakdown could improve scannability, but it's appropriately detailed.

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 of this complexity with no output schema and 23 optional parameters, the description is remarkably complete. It covers all major actions, explains invocation behavior (including auth and payment flows), differentiates install vs invoke, notes permission requirements, and details the prompt library. It leaves few ambiguities about how to use the tool effectively.

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 adds crucial meaning to the parameters, especially action, query, mcp_id, tool_id, arguments, and prompt-related fields, by explaining them through the workflow (e.g., action=search, describe returns profile, invoke runs tool). However, not all 23 parameters are explicitly explained (e.g., immediate, conversation, prompt_targets), leaving some gaps for less common fields.

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, a platform for discovering, describing, and invoking MCP tools, plus a prompt library. It specifies the core flow (search → describe → invoke) and distinguishes itself from siblings, which are specific standalone tools (e.g., authenticate, 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 explicit when-to-use guidance for each action: use search to find MCPs, describe for profiles, invoke for one-off runs, install for permanent toolkit additions, and it even says 'prefer invoke for single/occasional use' vs 'use install only to make an MCP PERMANENT'. It also covers the prompt library actions and mentions that writes require 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 already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description does not need to repeat these. The description adds the reproduction context for the 'conversation' parameter, which is a minor behavioral insight. However, it doesn't mention response behavior, rate limits, or any side effects beyond what annotations 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?

Two crisp sentences. The first front-loads the purpose, the second provides actionable guidance. No fluff, 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 bug-report tool with no output schema and safe annotations, the description is mostly adequate. It covers what to do and hints at reproduction steps. However, it could benefit from a note on whether the tool returns any feedback or if invocations are fire-and-forget, especially since idempotentHint=true implies repeated calls are acceptable.

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 is expected to clarify parameters. It does explain that 'conversation' should contain recent messages for reproduction, adding value. However, it refers to it as an 'array' while the schema defines it as a string with a JSON-array default, which could confuse. The required 'message' field and optional 'context' are not elaborated, leaving some gaps.

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 and resource: 'Report a bug, missing feature, or send feedback.' This unambiguously differentiates it from sibling tools like 'show_version' or 'authenticate', which serve entirely different functions. The scope is immediately evident.

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 a clear context for use by listing three valid scenarios (bug, missing feature, feedback) and gives a concrete usage guideline: 'Include the conversation array with recent messages for reproduction.' While it doesn't explicitly name alternative tools, the context is clear and the tip instructs on how to use it effectively.

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 and idempotentHint, and the description adds specificity by stating it returns current platform and adapter versions. No contradictions exist, and for a read-only getter, no further disclosure is necessary.

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, tight sentence that front-loads the action ('Show') and clearly specifies the object. No fluff, perfectly sized for the tool's trivial nature.

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 tool with no output schema, the description fully covers its purpose and behavior. No gaps exist that could mislead 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?

With zero parameters, the schema provides no semantic load, and the description adds the context of what is returned. The baseline of 4 for 0-param tools applies here, as there is nothing more 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 uses a specific verb ('Show') and resource ('MCP platform and adapter versions'), making its purpose immediately clear. It distinguishes itself from siblings like authenticate, connect, and marketplace, which address entirely different functions. No ambiguity about what this tool does.

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 whenever version information is needed, which is contextually clear given the tool's simplicity. However, it does not explicitly state when not to use it or name alternatives, but the sibling set contains no competing version tool, so the context is sufficient for a 4.

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 comprehensively cover the safety profile (readOnlyHint: true, idempotentHint: true, destructiveHint: false), and the description adds value by detailing what the returned state contains. No contradiction — the description's read-verb matches the read-only annotation. It doesn't disclose additional behaviors like auth requirements or rate limits, but for a stateless inspection tool the bar is mostly met by the annotation coverage.

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?

Single sentence, front-loaded with the verb and resource, and uses a colon-led enumeration to pack the full return description into one compact line. Every word earns its place; zero 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?

With no output schema present, the description compensates by enumerating the return content (installed MCPs, connection statuses, accounts, catalog counts). Annotations cover the safety profile. It could mention when to invoke (e.g., pre-connection check), but for a no-parameter state-inspection tool the coverage is strong.

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 secret: special, schema coverage is trivially 100% (empty properties). Per rubric, 0 params = baseline 4. There is no parameter meaning for the description to add beyond what the schema already implies.

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') with a clear resource ('toolkit state') and enumerates exactly what it returns: installed MCPs, connection status, accounts, and catalog tool counts. This clearly distinguishes it from sibling tools like authenticate and connect, which are about establishing connections rather than inspecting state.

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 purpose evident (inspecting current toolkit state) but offers no explicit when-to-use or when-not-to-use guidance. The context is reasonably clear — an agent would call this to check what's installed/connected — but it doesn't name alternatives or exclusions, relying on the reader to infer the division of labor among siblings.

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 description's 'consulta' is consistent. The description adds valuable context beyond annotations: it specifies payment requirements, clarifies that the data is official and non-confidential, and notes the client's LGPD responsibility. These details enrich the behavioral profile 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 several clauses covering purpose, hosting, payment, and legal disclaimers. It is front-loaded with the primary intent, but the legal and payment details add length. While not overly verbose, it could be more concise by separating essential usage info from disclaimers. Still, it's reasonably 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?

There is no output schema, yet the description does not explain what the response will contain, such as case details, status, or parties. It also lacks information on error handling, limitations, or expected result format. Given the tool's purpose and lack of an output schema, this is a significant gap that prevents full understanding of the tool's behavior.

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 for its two parameters, and the description does not compensate by explaining 'numero_processo' (process number) or 'grau' (degree). The description only mentions 'Consulta Processual' but gives no hints about parameter formats, required vs optional usage, or examples. This leaves the agent to infer from the tool name, 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 this is a procedural consultation for TRT17 in an official source. The tool name and first sentence ('Tribunal TRT17: Consulta Processual, consulta em fonte oficial') distinguish it from the generic sibling tools (authenticate, connect, etc.). It could be more specific about what the consultation returns, but the core purpose 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 mentions practical details like payment (pague por consulta com crédito pré-pago) and that no platform credentials are needed, which implies conditions for use. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. Since there are no sibling tools for tribunal queries, the usage context is implied but not clearly articulated.

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