Tribunal TRF3: Certidão de Distribuição

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

With annotations indicating idempotent behavior and no destructive effect, the description adds meaningful context about token persistence ('permanent, non-expiring connection'), session-only limitations, and the browser-link flow. It doesn't disclose potential security caveats like token exposure, but the added connection-lifetime details elevate this above annotation-only transparency.

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 slightly wordy but each chunk of information earns its place: setup context, permanent-auth option, session-auth option, and invocation patterns. It is reasonably front-loaded with the audience ('MCP.AI for IDE agents') and overall compact enough for a parameter with multiple usage paths.

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 that this tool has one optional parameter, no output schema, and a straightforward auth purpose, the description covers both the setup workflow and the token/paste mechanics. It lacks only a note about what the response contains in each branch, but for such a focused login helper the guidance is sufficiently 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 schema merely lists a single string 'token' with zero description, so the description carries the full semantic burden. It fully explains the meaning of the parameter as a JWT to paste after login, shows exact usage via { token: "<jwt>" }, and clarifies the no-argument case for retrieving the login link.

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 handles authentication/login for the MCP.AI server used by IDE agents, with explicit steps for browser login and token pasting. It distinguishes itself from siblings like 'connect' by focusing on credential acquisition and token setup, though the wording 'MCP.AI' is slightly service-specific and could be clearer.

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 strong usage context: it explains the recommended permanent configuration via header vs session-only login, and explicitly when to call with a token vs with no arguments to get a link. It doesn't explicitly compare against alternative tools but does provide clear within-tool decision 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 communicate safety (readOnlyHint, idempotentHint, destructiveHint false), so the bar is lower. The description adds useful conditional behavior: what is returned when all providers are connected versus when credentials are missing, including authenticated and pending fields.

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-loads the main purpose, and each sentence adds meaningful information. No redundant wording or elaboration.

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 is sufficiently complete. It describes both primary states and the key returned data fields, allowing an agent to understand what to expect when invoking 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 tool takes zero parameters, so there are no parameter semantics to explain. The description adds value by explaining the return state, which is the relevant semantic content for this tool.

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 identifies the resource (connection status and URLs). It also differentiates from sibling tools like authenticate by being a status read rather than an authentication 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 provides clear context for when to call the tool: to check connection status and obtain URLs in cases where credentials are missing. It does not explicitly name alternative tools or state when not to use it, but the usage context is implied naturally.

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, the description discloses that invoke runs tools one-off even when not installed, that writes require workspace owner/admin, and that auth/payment issues return connect or checkout links. It also clarifies that install permanently adds MCPs to the toolkit. 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 long but appropriately so for a 23-parameter multi-action dispatcher. It is well-structured: core flow, invoke behavior, install guidance, billing, reporting, and prompt library are each addressed in a natural order with minimal 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?

Given the tool's complexity and the absence of an output schema, the description covers the main return behaviors (connect link, checkout link, full profile, shareable prompt link) and operational constraints. It is not exhaustive—error cases and several parameters are unaddressed—but it is substantially complete for a tool of this 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?

With 0% schema description coverage, the description carries the parameter-semantics burden and does explain the key action enum values and the meanings of mcp_id, tool_id, arguments, and several prompt_* fields. However, many of the 23 parameters—such as limit, query, immediate, tier_slug, conversation, cancel_reason, and report_context—are never explained.

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 mcp.ai marketplace catalog and runner, with a concrete search → describe → invoke flow. It is broad because it covers many actions and the prompt library, but the core purpose is unmistakable and distinct from siblings.

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?

Excellent guidance: it explicitly says when to use invoke vs install, when to prefer invoke for one-off use, and how to handle auth/checkout flows. It also distinguishes subscribe/cancel, list_tools, report_bug, request_mcp, and the prompt-library actions.

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 communicate idempotency and non-destructiveness. The description adds that the conversation array should be provided for reproduction, but does not explain side effects, output, or whether the report is visible somewhere. 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, focused sentence with no fluff. It front-loads the core purpose and the only key invocation detail, the conversation array.

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 is simple enough that a minimal description can be viable, and the schema already defines defaults for optional parameters. However, there is no output schema and no explanation of the required 'message' field's format, so the agent must infer important invocation details.

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 only clarifies the 'conversation' parameter; the required 'message' parameter and the optional 'context' parameter are not elaborated. The guidance is incomplete.

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 explicitly states the tool 'Report a bug, missing feature, or send feedback,' giving a specific verb and target scope. It clearly distinguishes this from unrelated sibling tools like authenticate or 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?

The description explains what to include ('conversation array with recent messages for reproduction'), which communicates a key usage requirement. It does not explicitly name alternatives or exclusions, but context implies report/feedback is the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds specificity by naming exactly what is shown (platform and adapter versions), which goes beyond the generic annotation hints. No contradictions.

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 fully conveys the tool's function without extraneous detail. It is front-loaded and efficient.

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 strong annotation coverage), the description is complete. It states exactly what the tool does, and annotations cover side effects and idempotency.

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 there is no schema to clarify. The description effectively communicates the tool's purpose, which is all that is needed given no parameters exist.

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: showing current MCP platform and adapter versions. It uses a specific verb ('show') and resource ('versions'), and is distinct from sibling tools like authenticate or 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?

No usage guidelines are provided. The description does not mention when to use this tool vs. alternatives, nor any prerequisites or context (e.g., checking version compatibility). It leaves the agent to infer appropriate usage.

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 return-content detail (installed MCPs, connection status, accounts, catalog tool counts) which goes beyond the annotations. No contradictions.

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 sentence that communicates exactly what the tool does without filler. Front-loaded with the verb 'Returns' and resource 'toolkit state'.

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 differentiating, the description fully explains what callers will receive. Given the tool's simplicity, the one-sentence summary is adequate and 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?

There are zero parameters, and schema coverage is 100% vacuously. Baseline for 0 parameters is 4. The description doesn't need to explain parameters; it adds value by describing output content instead.

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 the current toolkit state, enumerating installed MCPs, connection status, connected accounts, and catalog tool counts. This is a specific verb+resource that distinguishes 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 description implies usage for inspecting toolkit status but does not explicitly state when to use vs. alternatives or provide exclusions. It's clear enough for an obvious info-gathering tool, but lacks explicit 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?

Beyond the read-only and non-destructive annotations, the description discloses that the tool requires prepaid credits and works without platform credentials. It also states that the data is not confidential and clarifies the client's data controller role, adding useful behavioral 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 relatively short but repeats similar points about official sources, payment, and privacy. Some legal language (LGPD) and repeated statements could be condensed without losing essential information.

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 gives key context about the certificate's official nature, payment requirements, and data privacy. However, it does not describe the output format, required input combinations, or how to interpret results, leaving significant gaps for a user unfamiliar with the domain.

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 description provides no explanation for any of the 14 parameters. Parameter names like 'abrangencia', 'tipo_documento', and 'nome_social' are ambiguous without descriptions, and the schema also lacks explanatory text, leaving users to guess their meanings and usage.

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 action (querying a distribution certificate) and its target (TRF3). It explicitly mentions the official source and distinguishes the tool from other possible certificate queries by specifying the court and type.

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 no guidance on when to use this tool versus alternatives. It mentions payment and lack of platform credentials, but these are operational requirements rather than usage conditions or recommendations.

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