Tribunal TJSP: Selo Digital

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

The description adds behavioral context beyond annotations by explaining the browser login flow, the permanent vs session-only distinction, and the config header option. It does not cover response details or error handling, but the key side effects are disclosed.

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 serves a purpose, though the phrasing is a bit run-on. It is not overly long and conveys necessary usage details.

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 auth tool with no output schema, the description explains the main flows and configuration, but it omits explicit return values for token submission and potential error cases, leaving some inference 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?

The schema has one optional parameter with no description, and the description fully compensates by explaining that 'token' is a JWT used for session-only login and that no arguments returns the link. This gives complete parameter semantics.

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: authenticating an IDE agent via browser login and token submission. It distinguishes from siblings by being the dedicated auth tool, though it does not explicitly contrast with 'connect'.

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?

It provides explicit usage guidance: permanent configuration via Authorization header, session-only login via pasted token, and calling with no args to get the link. It does not mention alternatives like 'connect', but the two described modes give clear context.

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, but the description adds valuable context by detailing the conditional return behavior: authenticated:true with empty pending[] when all connected, and connect_url plus per-install URLs when credentials are missing. This goes beyond annotations without contradicting them.

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 long, with the main purpose front-loaded in the first sentence and conditional details in the second. Every clause adds information, with no redundant wording or padding. This is exemplary conciseness.

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 params, no output schema), the description covers the two main scenarios well: fully connected and missing credentials. It does not explicitly mention partial connection states, but this is somewhat implied by the presence of pending[]. The annotation set is solid, and the description adds enough behavioral detail to be considered complete for most uses.

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%. Per baseline guidance, 0 params merits a score of 4. The description correctly does not invent parameter semantics, and its explanation of behavior compensates for the lack of parameter-related detail.

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: 'Returns connection status and URLs.' This is a specific verb+resource that distinguishes it from siblings like 'authenticate' (which handles authentication) and 'show_version' (which shows version info). The description meaningfully differentiates the tool's role.

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 context: to check connection status and get URLs when credentials are missing. It provides clear context about what to expect in different states (all connected vs. missing credentials), but it does not explicitly state when NOT to use this tool or mention alternatives like 'authenticate'.

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 provide readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true, but the description goes beyond these with valuable behavioral details: writes require workspace owner/admin, invoke's one-off execution doesn't add to toolkit, invoke returns connect/checkout links for credentialed/paid MCPs, and search/describe flag installation status. However, it doesn't describe error scenarios, rate limits, or what happens when an invoke fails after a connect/retry sequence. The description adds meaningful transparency but not exhaustive behavioral coverage; thus a 3 is appropriate given the annotation baseline and the extra context 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 a single large paragraph with dense information, covering the catalog, execution flow, permission model, and prompt library in one continuous stream. It is front-loaded with the core concept (catalog + runner) and the core flow, but it becomes a wall of text and could be better structured with bullets or paragraphs. It covers a lot of ground efficiently, but the lack of structural organization hurts readability. Given that it is information-dense but not structured, a 3 is suitable.

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 complexity (a dispatcher tool with 23 parameters, 14 enum actions, 0 annotations for the description, no output schema), the description is quite comprehensive. It explains the overall purpose, core flow, edge cases (credential/payment), permissions (owner/admin for writes), and the prompt library side. It lacks some action-specific details for the less common actions like report_bug, request_mcp, subscribe, and cancel conditions, but the main use cases are fully covered. Since the description must carry the burden due to 0% schema coverage and no annotations, it performs well, but could still enumerate the specific parameters per action for completeness. Thus a 4 is justified, as it is close to complete for a complex 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?

Schema description coverage is 0%, so the description must compensate. It explains the action enum by listing all value meanings (search, describe, invoke, etc.) and covers the main parameters (mcp_id, tool_id, arguments, prompt_slug, etc.) within the context of workflows. It explains the action-dependent params (e.g., prompt_vars for prompt library, cancel_comment for cancel) but doesn't give detailed format/schema for complex params like arguments or prompt_vars (JSON strings). Given that the description is thorough in explaining what each action requires, it adds semantic meaning beyond the bare schema (which has default values but no descriptions). This is a moderate-to-good compensation, earning a 3; it could improve by specifying the expected JSON structure for arguments and prompt_vars.

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 'marketplace' is the official mcp.ai catalog and execution platform, covering capability requests like 'find an MCP that does X' and 'consulta um CPF'. It distinguishes this tool from its siblings by specifying all major action types and by noting that it is the in-platform catalog and execution mechanism. However, it is a multi-purpose dispatcher tool, so it lacks a single resource-specific verb, but it conveys its broad role effectively in the ecosystem.

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 extensive usage guidance: it explains the core flow (search → describe → invoke), when to use invoke instead of install (one-off vs permanent), that invoke works even when MCP not installed, and that install is for permanent additions. It also mentions the prompt library sub-actions (search_prompts, get_prompt, publish_prompt) and covers specific scenarios like credential required and payment required. It does not explicitly say when to use alternative sibling tools, but it clearly delineates the sub-actions available in this tool, giving clear when-to-use instructions for the key modes.

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 idempotentHint:true and readOnlyHint:false, but the description adds the expectation of including a conversation array for reproduction. It doesn't describe side effects (e.g., creating a ticket) or response behavior, but the basic actionable behavior is disclosed without 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 short sentences: the first states the purpose, the second gives a key usage hint. No fluff, front-loaded, and every word adds value.

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 reporting tool, the description covers the core action. However, it doesn't clarify the required 'message' field or the format of the 'conversation' string (e.g., JSON array). Given no output schema exists, slightly more detail (e.g., mentioning required fields) would improve completeness.

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 must compensate. It explains the 'conversation' parameter's intended use ('recent messages for reproduction') but gives no information about the required 'message' parameter or 'context'. This mismatch could confuse an agent into thinking conversation is required.

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.' The verb 'report' plus resource ('bug, missing feature, feedback') leaves no ambiguity. This is distinct from 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 gives practical guidance on what to include ('Include the conversation array with recent messages for reproduction') but doesn't explicitly state when to use this tool vs alternatives or mention any exclusions. Since no sibling is similar, this is acceptable but not fully 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?

The annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, which describe the safety profile. The description adds no additional behavioral context beyond the purpose, such as side effects or network calls. It is adequate but not enriched 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?

The description is a single, front-loaded sentence with no waste. It conveys exactly what is needed without redundancy.

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 a clear output (versions), the description is complete. No output schema is required, and the behavior is fully implied by the purpose and annotations.

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 schema description coverage is trivially 100%. The baseline for no parameters is 4, as no parameter explanation 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 clearly states it shows the current MCP platform and adapter versions, using a specific verb and resource. It is distinct from sibling tools like authenticate or report_bug, 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?

The context is clear that this tool is for retrieving version information, and given the sibling list, it is self-evident when to use it. However, there is no explicit mention of alternatives or exclusions, so it slightly misses the full 'when/not' 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, idempotentHint, and destructiveHint false, and the description does not contradict them. It adds value by specifying the exact state details returned (MCPs, statuses, accounts, catalog tool counts), which goes beyond the structured annotations. No side-effect caveats are needed since this is a read-only inspection 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, well-structured sentence that front-loads the purpose ('Returns the current toolkit state') and follows with a colon-delimited list of specific output contents. Every phrase adds meaningful information with no filler 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 zero-parameter, read-only informational tool, the description enumerates all relevant output categories: installed MCPs, connection status, connected accounts, and catalog tool counts. With no output schema present, this provides sufficient understanding of return values. No additional side-effect or prerequisite context is 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?

The tool accepts zero parameters, so parameter semantics are trivial and the schema fully covers all possible inputs. The description appropriately focuses on output semantics rather than input guidance, matching the baseline for parameterless tools.

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') while enumerating exact data points: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly differentiates it from sibling tools like show_version or connect by focusing on aggregate state introspection.

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 use when an agent needs to inspect the current toolkit state, but it does not explicitly state when to prefer this tool over alternatives or provide exclusions. No prerequisite or alternative guidance is included, so the usage context is only inferred.

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. The description adds valuable context beyond this: cost implications (prepaid credit), no credential requirement, non-confidential nature, and LGPD compliance responsibilities. It doesn't mention rate limits or failure modes, but the added info is meaningful.

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 of four sentences, each carrying relevant information (official source, payment model, data nature, legal responsibility). No redundancy, but could be slightly better structured with bullets for 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?

For a read-only query tool with one parameter and no output schema, the description covers key aspects like cost and data sensitivity. However, it lacks parameter format and return value expectations, making it incomplete for an agent to invoke correctly without additional 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?

With schema coverage of 0% and only one parameter 'selo', the description fails to explain what format or value 'selo' expects (e.g., a code, a string pattern). The agent has no guidance on how to construct a valid query, which is a significant gap.

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 queries a digital seal (Selo Digital) from the TJSP court in an official source. The verb 'consulta' (query) and resource are specific, and it's distinct from 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 the operational context (no platform credentials, prepaid credit per query, official source) but doesn't explicitly state when to prefer this over other tools. However, given the specialized nature and lack of alternatives, this is sufficiently clear.

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