Tribunal TST: Banco de Falências

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

Annotations already indicate readOnlyHint=false and idempotentHint=true, so the agent knows it's a mutation. The description adds useful behavioral context: it can either set a session-only token or return a login link, and explains the permanent header alternative. It doesn't mention side effects like token storage or expiration, but the main behavioral traits are disclosed 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 three sentences and somewhat wordy, starting with 'MCP.AI for IDE agents' which is more context than essential. It delivers the key points but could be more concise and front-loaded. For example, it could simply say 'Returns a login link, or accepts a token for session-only authentication.' It's not excessively long, but not tightly written either.

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 authentication tool with one optional parameter and no output schema, the description covers the main behaviors: two modes (token vs no-args), the distinction between permanent and session-only, and the intended audience. It lacks detail on error cases, token format validation, or what the returned link looks like, but these are non-essential for an agent to use the tool correctly. Overall, reasonably 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 only lists an optional 'token' string with zero description coverage. The description compensates by explaining exactly how to use the token parameter: call with { token: "<jwt>" } for session login, or call with no arguments to get the link. This fully clarifies the parameter's purpose and optional nature, going well beyond the inactive schema.

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 indicates the tool handles authentication: it explains how to log in via browser, copy the access token, and either configure a permanent header or use a session token. Though the wording is somewhat indirect ('log in in the browser'), the purpose is evident and distinct from siblings like connect or toolkit_info. It could be more explicit that the tool returns a login link or accepts a token, but it's clear overall.

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 distinguishes between two usage scenarios: for permanent, non-expiring access, add the token to the server config as a header; for session-only login, call this tool with a token or with no args to get a link. It provides clear when-to-use and when-not-to-use guidance, and even names an alternative approach (config header). This is strong usage 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?

The description transparently discloses behavior by explaining different response outcomes based on whether all providers are connected or credentials are missing. It mentions specific fields like 'authenticated:true' and 'connect_url', providing insight into expected output without revealing internal logic.

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, consisting of two sentences that convey the essential information. It avoids unnecessary detail while still explaining conditional outcomes, which is appropriate 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?

Given the lack of parameters and output schema, the description sufficiently explains what the tool returns and under what conditions. It provides enough context for a user to understand the tool's function, though it could benefit from a brief note on when to call it.

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 no parameters, so there is no ambiguity or missing parameter documentation. The schema coverage is complete (empty properties), making parameter semantics a non-issue.

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 that the tool returns connection status and URLs, which is a specific and understandable purpose. It distinguishes itself from sibling tools like 'authenticate' and 'marketplace' by focusing on status retrieval rather than actions.

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 when one wants to check connection status, but does not explicitly state when to use it versus alternatives. It lacks guidance on prerequisites or typical scenarios, such as 'use after authentication' or 'use to verify connectivity before other operations.'

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 substantial behavioral context beyond annotations: invoke works even when the MCP is not installed, returns connect links for missing credentials, and returns checkout links for empty wallets requiring retry. It also disclosed admin requirements for writes and the prompt library characteristics, enriching the annotation profile.

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 single paragraph covering many actions and nuances. While every detail is relevant, the lack of bullet points or structure makes it harder to scan. It is long but not strictly concise; a structured layout would improve readability.

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 (14 actions, no output schema), the description covers most key behaviors: the search/describe/invoke flow, pricing/auth handling, installation semantics, permissions, and the prompt library. It omits some edge parameters like 'resume' or 'conversation', but the overall scope is well-covered for common 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?

With 0% schema description coverage, the description carries the full burden for parameter meaning. It explains the action enum values, the flow of mcp_id and tool_id, and the arguments parameter for invoke. However, it does not explicitly detail all 23 parameters (e.g., cancel_reason, prompt_vars, immediate), so it adds significant semantics but not exhaustive coverage.

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 defines the tool as the official mcp.ai marketplace, serving as both a catalog and execution layer for MCPs/tools. It specifies concrete actions (search, describe, invoke, install) and distinguishes its role from sibling tools by describing the core flow and when to use alternatives like report_bug or request_mcp.

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, such as preferring invoke for single/occasional use vs install for permanent toolkit membership, and using list_tools to see currently callable tools. It also states that request_mcp is for building new MCPs when nothing fits, giving clear 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 already declare idempotentHint=true and destructiveHint=false, covering the safety profile. The description adds the instruction to include the conversation array, which is a useful behavioral detail, but beyond that it doesn't describe what happens on submission or any side effects.

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 main purpose, and every word contributes value. No fluff or repetition.

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 feedback tool with no output schema and few parameters, the description provides enough context to invoke it correctly. It mentions what to include for reproduction, and the sibling tools are clearly unrelated. A minor gap is not explaining what the response might be, but that is not required.

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 only mentions the conversation array, but does not clarify the 'message' (required) or 'context' parameters. The description gives partial guidance but fails to fully explain all parameters.

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's purpose: 'Report a bug, missing feature, or send feedback.' This is a specific verb+resource that clearly 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 when to use it (for reporting issues or feedback) but does not explicitly contrast with alternatives. It provides a usage hint for the conversation parameter but no when-not-to-use 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 the tool as read-only and idempotent, so the description doesn't need to repeat that. It adds value by specifying exactly what versions are shown (platform and adapter), which is behavioral context 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?

A single, short sentence that conveys the complete purpose without any filler. Every word is essential, making it optimally 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?

For a simple no-parameter tool with no output schema, this description is fully sufficient. It tells the agent exactly what the tool does, and given the low complexity, there are no missing details that would affect successful invocation.

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 baseline is 4. The description has no parameter details to provide, and the schema already covers all parameters (none), so nothing further is 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 uses a specific verb 'Show' and identifies the resource (MCP platform and adapter versions). It clearly distinguishes this tool from siblings like authenticate, connect, or report_bug, making its 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 provides no guidance on when to use this tool versus alternatives, nor any context about its role (e.g., diagnostic or support). It simply states what it does without any situational cues.

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, covering safety. The description adds concrete details of what the state includes, complementing the annotations without contradicting them. No extra behavioral context like rate limits is needed for a read-only 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 a single, front-loaded sentence that lists the returned information efficiently. No filler or redundancy; every word contributes to the purpose.

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, the description fully explains the return content, covering the key attributes (installed MCPs, status, accounts, tool counts). This is complete for a low-complexity informational tool, and no further details on errors or edge cases are necessary.

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 for parameter semantics is 4. The description does not need to elaborate on parameters, and its focus on the return content 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 returns the current toolkit state with specific components: installed MCPs, connection status, accounts, and catalog tool counts. This is specific and distinguishes it from siblings like show_version or authenticate, which have 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?

The description implies when to use this tool (to inspect toolkit state) but provides no explicit guidance on when not to use it or mention of alternatives. Since the purpose itself makes the context obvious, an implied usage is present, but exclusions are absent.

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?

While annotations already mark the tool as read-only and idempotent, the description adds meaningful details: the data is not confidential, the client is the data controller, and the query incurs a cost. This goes beyond the structured annotations and informs the agent of non-obvious behaviors.

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-loaded with the core purpose, followed by payment and legal context. It is not overly verbose for the amount of information conveyed, though it could be seen as slightly dense with disclaimers.

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 read-only tool with no output schema, the description covers the source, payment, and governance nicely. However, it leaves ambiguity about parameter usage and whether at least one filter is required. The three optional parameters lack guidance, making the tool feel incomplete without external knowledge.

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% with three parameters (cnpj, razao_social, numero_processo) and the description does not explain their usage, whether any combination is required, or how they map to bankruptcy records. Since schema coverage is low, the description should compensate but fails to do so.

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 query operation ('consulta') on the TST Bankruptcy Database ('Banco de Falências') from an official source. It uses a specific noun phrase and implies a read-only lookup, but it does not explicitly differentiate from sibling tools, as the calibration example 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 provides context on appropriate usage: it queries official Brazilian sources, notes the pay-per-query model with prepaid credit, and outlines LGPD responsibilities. It does not mention explicit alternatives or exclusions but gives enough context for an agent to infer when to use it.

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