Tribunal TRF1: Processo

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

The description discloses significant behavioral details beyond the annotations: it explains the permanent vs. session-only nature, the option to store the token in the server config, and the no-args behavior (returns a link). Annotations only indicate idempotentHint and non-destructive, so the description adds relevant side-effect context 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 front-loads the primary purpose and then provides essential usage details in three sentences. It is slightly verbose but every sentence contributes necessary information (two modes and the no-args alternative). No unnecessary fluff, but could be tightened slightly.

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 the main flows: how to get the link, how to use a pasted token, and the optional permanent config approach. It does not mention the return value of the tool (e.g., success message or token validation), but given the minimal schema and lack of output schema, the description is reasonably complete for a simple authentication 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 has no description for the token parameter (0% coverage), but the description compensates by explaining its purpose: 'call with { token: "<jwt>" } after the user pastes', and the optional no-args case. This adds meaning beyond the bare schema, making the parameter's semantics clear.

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: logging in the browser and obtaining an access token for MCP.AI. It explicitly mentions IDE agents like Cursor and differentiates from generic connection tools (e.g., connect) by focusing on the token-based authentication flow and the two usage modes.

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 on using the tool for login, including two invocation patterns: passing a token for session-only login or calling without args to get a link. It recommends the config header approach for permanent connections. However, it does not explicitly exclude alternative tools or state when not to use this tool, so it misses the 'when-not/alternatives' criterion for 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, destructiveHint=false, so the agent knows it's a safe read operation. The description adds useful behavioral details about the conditional return values (authenticated:true when all connected, connect_url when missing credentials), which is beyond what annotations provide. Not contradicting 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?

Two sentences, directly to the point, no filler. The description is front-loaded with the main action ('Returns connection status and URLs') and then provides conditional behavior details. Perfectly 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 tool has no parameters and annotations already convey safety and idempotency, the description is quite complete. It explains the return values in different scenarios (all connected vs. missing credentials). However, it doesn't mention the exact structure of connect_url or per-install URLs, which might be useful, but output schema is absent and the description covers key aspects.

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?

There are no parameters, so the baseline is 4. The description doesn't need to elaborate on parameters. The schema coverage is 100% (empty). The description focuses on output semantics, 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 what the tool does: returns connection status and URLs. It distinguishes itself from siblings by focusing on status/URLs rather than authentication actions (authenticate) or information lookup (toolkit_info). Slightly less explicit about the resource scope (connection status of what? providers).

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 on when to use this tool versus alternatives. It implies usage for checking connection status, but doesn't mention when not to use it or when to use authenticate or toolkit_info instead. The description is mostly descriptive, not prescriptive.

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?

Discloses significant behavioral details beyond annotations: invoke works even for non-installed MCPs and runs one-off without bloating the toolkit; install makes permanent; search/describe flag installation status; writes require admin. Also explains return behaviors like connect/checkout links. 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 lengthy wall of text covering many facets. While it is front-loaded with the purpose, it rambles into extensive detail and includes redundant explanations (e.g., repeated mentions of connect/checkout). A more structured breakdown per action would be far more scannable. It is not concise; every sentence does not earn its place relative to the overload.

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, many actions, no output schema), the description is fairly complete at the flow level: it explains the main actions, auth requirements, and expected behavior (links, installs). However, it leaves many parameters unexplained and does not cover every action's specific inputs (e.g., request_details, cancel_reason, prompt_targets). Still, for a first-pass understanding, it is largely sufficient.

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 high-level meaning of action enums (search, describe, invoke, etc.) and some parameters indirectly (e.g., tool_id, arguments for invoke), but does not clarify most of the 23 parameters (limit, query, mcp_id, message, immediate, tier_slug, prompt_* etc.). Many parameters remain opaque, leaving the agent without enough detail to correctly construct calls.

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 the official marketplace catalog and runner, with a detailed breakdown of actions. It effectively distinguishes from sibling tools like report_bug (which is a sub-action here) and covers core functionality, though it is a multi-purpose tool with many functions.

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 explicit guidance on when to use each action: core flow (search → describe → invoke), prefer invoke over install for one-off uses, use install for permanence, and mentions billing actions like subscribe/cancel. Also includes conditional flows (connect link for auth, checkout for payment) and notes that writes require owner/admin. Clearly defines when and when not to use 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 declare readOnlyHint=false (write operation) and idempotentHint=true (safe to retry). The description adds context by specifying the need for conversation data for reproduction, which is beyond the annotations. However, it does not disclose side effects (e.g., whether a ticket is created, logs stored) or any user-visible consequences. Given the annotations cover safety traits, the description adds some but not rich behavioral detail.

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 extremely concise: two sentences that front-load the purpose and provide a key usage tip. Every word contributes value; there is no fluff or repetition. This is an ideal length for a simple tool.

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 the main purpose and one important behavioral requirement (conversation for reproduction). However, it omits explanations for the 'context' parameter and does not describe the return value or post-submission behavior (no output schema exists). Given the tool is simple and annotations provide safety info, the description is adequate but not fully 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?

Schema description coverage is 0%, so the description must compensate. It explicitly explains the 'conversation' parameter (include recent messages for reproduction) and implicitly covers 'message' via the verb (report bug/feedback). However, the 'context' parameter is not mentioned or clarified. With 3 parameters and 0% schema coverage, the description partially compensates but leaves 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: 'Report a bug, missing feature, or send feedback.' It uses a specific verb (report) and identifies the resource types. Since sibling tools are unrelated (e.g., authenticate, marketplace), there is no ambiguity, making it highly distinguishable.

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 bug reporting and feedback but does not provide explicit when-to-use or when-not-to-use guidance. The instruction 'Include the conversation array with recent messages for reproduction' offers a concrete usage hint, but no alternatives or exclusions are mentioned. This is adequate but minimal for guiding tool selection.

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 agent knows this is a safe, non-mutating operation. The description adds that it shows versions, which is consistent. It does not add extra behavioral details like output format or potential errors, but given the annotations cover the safety profile, a 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, concise sentence that directly states the tool's function. It is front-loaded and contains no unnecessary words. It earns its place perfectly.

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, clear annotations), the description is complete enough. It tells the agent exactly what the tool does. The only minor gap is that it doesn't specify the format of the version output, but that is not critical for a simple version query. The annotations and schema provide sufficient context.

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% (vacuously). The description does not need to explain parameters because there are none. The baseline for 0 params is 4, and the description is clear about what it does, so this score is justified.

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: showing current MCP platform and adapter versions. It uses a specific verb ('show') and resource ('versions'), and it distinguishes itself from sibling tools like 'toolkit_info' by focusing on version information. However, it could be slightly more explicit about what 'platform' and 'adapter' refer to, but the meaning is clear enough.

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 that this tool is used when the user wants to know the current versions of the MCP platform and adapter. It does not explicitly state when to use it versus alternatives, but given the sibling tools (e.g., 'toolkit_info' might provide broader info), the context is somewhat clear. There is no explicit exclusion or alternative mention, so it's adequate but not highly 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying exactly what the state snapshot includes, such as connected accounts and exposed catalog tool counts, going beyond the bare annotation.

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, front-loaded sentence that immediately states the outcome and then lists the key data points. Every phrase adds information, with no filler, repetition, or vague qualifiers.

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 info tool, the description covers the main return categories well. A minor gap is the lack of detail about the exact representation of connection statuses or account identities, but overall this is adequate for its simple 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?

The tool has zero parameters, so the parameter-semantics burden is minimal and the baseline is 4. The description appropriately focuses on the output content rather than inputs, and there are no undocumented parameters to compensate for.

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') and enumerates concrete contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly differentiates it from siblings like show_version or tribunal_trf1_processo_consultar.

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 that this is a state-inspection tool, useful for assessing installed MCPs and connection status. It does not explicitly name alternatives or when-not-to-use it, but the scope is unambiguous and no exclusions are needed for a zero-parameter info 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 signal read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond annotations: the tool is hosted by the platform, requires prepaid credit, accesses citizen-available official data, and imposes LGPD controller responsibilities on the client. 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 is compact and front-loaded with the core purpose. The additional sentences about payment, official sources, and LGPD are relevant operational context, though the final clause is somewhat legal boilerplate and not strictly necessary for tool invocation.

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 six optional parameters and no output schema, the description is not complete enough for reliable invocation: it offers no parameter semantics, expected combinations, or result expectations. Annotations cover safety traits, but the actual query contract remains ambiguous.

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%, yet the description provides no guidance about any of the six parameters (cpf, oab, cnpj, parte, advogado, processo). It does not clarify valid formats, required combinations, or which identifier should be supplied for a query, 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 verb and resource: consult ('consulta') TRF1 process data in an official source. It also distinguishes itself from the sibling platform-level tools (authenticate, connect, marketplace, etc.) by explicitly naming the legal domain and query action.

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 useful context: it queries official public data, requires no platform credentials, and involves prepaid per-query credit. It does not explicitly name alternatives or when-not-to-use scenarios, but the sibling list makes those alternatives obvious and unrelated, so the context is clear.

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