Tribunal TRF3: Consulta Pública

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

Annotations provide only basic traits (idempotent, not destructive). The description adds useful context: the token acquisition flow, the difference between permanent and session-only logins, and that calling with no args returns a link. However, it does not specify what the tool returns when a token is provided (e.g., success/failure), which would be helpful.

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 verbose but well-structured: it introduces the purpose, then explains the two options in a clear sequence. Each sentence adds value, but it could be tightened by removing redundant phrasing like 'MCP.AI for IDE agents' if that is implied by context. Overall, it's efficient and front-loaded.

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 one optional parameter and no output schema, the description is largely complete. It covers both usage modes and the meaning of the parameter. The main omission is the return value when a token is provided—it only mentions what happens with no args (returns a link). Adding a note about the response would make it 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?

The schema has zero coverage (no description for 'token'), so the description carries the full burden. It clearly explains that 'token' is a JWT for session-only login and that it's optional (calling without it returns a link). This fully compensates for the missing schema description.

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: authentication for IDE agents. It explicitly says 'log in in the browser, copy the access token' and describes the two ways to authenticate (config header vs. session login). It distinguishes itself from siblings like 'connect' by focusing on token acquisition and login flow.

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 instructions: for permanent connection, add token to config; for session-only, paste token via parameter; or call with no args to get a link. It clearly explains when to use each mode and how to invoke the tool, leaving no ambiguity about the intended workflow.

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 safety profile is clear. The description adds conditional behavior (all providers connected vs missing credentials) and specifies the keys returned (authenticated, pending, connect_url), which enriches the behavioral context beyond 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?

Two concise sentences, front-loaded with the core purpose, then details edge cases. Zero 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?

For a tool with no parameters and no output schema, the description covers the two relevant states and the return values. It is fully complete for an agent to know what to expect. Sibling differentiation is not explicit but the tool's purpose is clear.

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 description does not need to explain parameter meanings. Baseline 4 for no-parameter tools, and the description provides context about the output based on state.

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: returning connection status and URLs. It explicitly differentiates from sibling 'authenticate' by indicating it provides status rather than performing authentication. The conditionality (all connected vs credentials missing) makes the purpose 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?

Implied usage: the description indicates when this tool is relevant (checking connection status) but does not explicitly say when to use it over alternatives like 'authenticate' or when not to use it. No exclusions or alternative recommendations are provided, leaving the agent to infer.

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 well beyond annotations, which only state readOnlyHint=false and destructiveHint=false. It discloses that invoke works without installation, returns connect links for credential-driven tools and checkout links for paid tools when the wallet is empty, requiring a retry. It also notes permission requirements ('Writes ... require workspace owner/admin') and the distinction between installed_in_toolkit vs installed_in_workspace. This is rich behavioral context not captured in 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 long (~450 words) but densely informative and logically organized: it starts with the core flow, then dives into the invoke vs install distinction, covers other actions, and ends with the separate prompt library. Each sentence earns its place; however, the undifferentiated wall of text could benefit from bullet points or section headers to improve scanability, though the content justifies the length.

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 thoroughly explains the tool's behavior, including one-off invocation, authentication/payment handling, permission requirements, and the prompt library. But it fails to provide any mapping between the 23 parameters and the actions, which is critical for actual usage. Given the complexity and lack of an output schema, the description is incomplete because it leaves the parameter layer entirely unaddressed.

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 23 parameters and 0% schema description coverage, the description must compensate by explaining how to use the parameters, but it does not. It mentions actions (search, describe, invoke, etc.) but never maps them to parameter names like query, mcp_id, tool_id, arguments, or limit. The agent has no idea how to populate the schema or what each parameter does, making the tool very hard to invoke correctly despite the excellent behavioral prose.

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 enumerates the core flow (search → describe → invoke) and distinguishes itself from siblings like authenticate and connect, which are separate concerns. The verb is specific and the resource (MCPs/prompts) 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 provides 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 contrasts invoke vs install: 'prefer invoke for a single/occasional use. Use install only to make an MCP PERMANENT.' It also covers when to use subscribe/cancel, report_bug, request_mcp, and the prompt library endpoints. There is clear exclusion guidance (e.g., 'without adding the MCP to the toolkit') and permission requirements for writes.

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 indicate the tool is idempotent and not destructive, but the description adds no context about side effects, auth requirements, or rate limits. The write nature is implied but not detailed, and no mention of what happens after reporting (e.g., ticket creation) is provided.

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 purpose, and no redundant information. It is concise, direct, and well-structured for quick comprehension.

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 low complexity and no output schema, the description covers purpose and one parameter but lacks details on expected behavior, output, or error handling. It is sufficient for a basic understanding 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 provides no descriptions, so the description must explain parameters. It only explains 'conversation' as for reproduction; 'message' (the required one) and 'context' are undefined. This leaves the most important parameter unclear.

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: reporting bugs, missing features, or sending feedback. It distinguishes from sibling tools which are unrelated (authenticate, connect, marketplace, etc.), making the purpose 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 explicitly mentions when to use: for bug reports, feature requests, or feedback. It also instructs to include the conversation array for reproduction, providing practical usage guidance. However, it does not mention any alternatives or when not to use, though this is less critical given the tool's specificity.

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, and the description is fully consistent. However, it adds no behavioral detail beyond the annotation hints, such as whether it makes network calls or returns cached data. With strong annotations, the bar is lower, so this scores as adequate but not additive.

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 with no fluff. Every word earns its place, and the structure is perfectly concise for a simple version-check 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?

For a zero-parameter, no-output-schema tool, the description fully covers what is needed: it specifies the exact information returned (platform and adapter versions). There are no missing pieces given the tool's trivial 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 tool has zero parameters, and the schema is empty, so there are no parameters requiring explanation. The description doesn't need to add parameter semantics. A baseline of 4 is appropriate for a parameterless 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 'Show the current MCP platform and adapter versions.' uses a clear verb ('Show') and specific resource ('MCP platform and adapter versions'), accurately distinguishing it from sibling tools like toolkit_info or marketplace. It leaves no ambiguity about what the 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?

Usage is implied by the simplicity of the tool; no explicit alternatives or exclusions are mentioned. While clear, it doesn't state when to prefer this over siblings or provide any caveats, so it meets the minimum viable 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 declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, non-mutating operation. The description adds meaningful context by specifying what information is returned (MCPs, statuses, accounts, counts), which is helpful beyond the annotations alone.

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, well-structured sentence that front-loads the main action and then lists the specific elements of the state. Every word adds value, 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?

Given there are no parameters and no output schema, the description carries the full burden of explaining the tool's return value. It does so comprehensively by listing all key components of the toolkit state. This is complete for a simple, read-only information 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 has zero parameters, so the description does not need to explain parameters. It instead elaborates on the return value, which is the useful semantics here. With no params, the baseline is 4, and the description fully compensates by clarifying the output.

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 verb 'Returns' and the specific resource 'current toolkit state', then enumerates the exact contents (installed MCPs, connection status, connected accounts, count of catalog tools). This distinguishes it from sibling tools like show_version or marketplace by focusing on overall toolkit state rather than a single aspect.

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 use the tool—when you need an overview of the toolkit's installed components and their status. It does not explicitly name alternatives or exclusions, but the context is specific enough that an agent can infer when this tool is relevant.

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 state readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral context beyond this: the query is hosted by the platform, requires no platform credentials, is paid per query with prepaid credit, and does not return confidential data. It does not, however, describe response structure, rate limits, or failure behavior.

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 concise and front-loads the core purpose: 'Tribunal TRF3: Consulta Pública, consulta em fonte oficial.' It is a single run-on sentence that mixes purpose, payment, and legal caveats, but each clause adds relevant context without excessive verbosity.

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 has no output schema, no required parameters, and no parameter descriptions, so the description carries the full burden of guiding invocation. It covers source legitimacy, payment, and data governance, but omits how to choose parameters, whether combinations are allowed, and what the response looks like, making it incomplete for reliable agent use.

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 mentions none of the five parameters (cpf, cnpj, nome_parte, nome_advogado, numero_processo). It also fails to clarify that all parameters are optional and whether at least one is required. The description provides no parameter-level meaning beyond what the parameter names themselves suggest.

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 a public consultation against the official TRF3 source, using a specific verb ('consultar') and naming the resource ('Tribunal TRF3: Consulta Pública'). It distinguishes itself from the generic sibling tools such as authenticate or report_bug, though it could be more explicit about exactly what court information is returned.

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 the tool is for querying official public Brazilian data available to citizens and emphasizes that the client is responsible for legitimate purpose under LGPD. It does not provide explicit when-to-use/when-not-to-use guidance or name alternatives, but the context is enough for a basic read-only query tool.

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