Tribunal TJSP: Processos do 2º Grau

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds behavioral specifics: calling with no args yields a login link, while calling with a token performs a session login. Side effects like session overwrites are not mentioned, but the idempotent hint mitigates this gap.

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?

Only two sentences, but the first is grammatically awkward ('log in in the browser'), and the second is long with multiple clauses. All information is useful, but the structure could be cleaner with clearer separation of the two modes.

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, it covers the main usage modes, token semantics, and recommended setup. It implies the response includes a link when called with no args, though it doesn't specify the full response format. Overall, it's 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 provides only a 'token' string with no description (0% coverage). The description fully compensates by explaining that token is an optional JWT pasted by the user, and that omitting it returns a login link. This is rich semantic guidance beyond the 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 states the purpose: to authenticate to MCP.AI by logging in and providing an access token. It distinguishes from siblings by focusing on the browser login flow for IDE agents, but doesn't 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 distinct usage scenarios: permanent config header versus session-only token, and explains when to call with no args (to get a link). This offers clear context for when to use each mode, though it doesn't explicitly mention alternatives or when not to use the 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 declare readOnlyHint:true and idempotentHint:true, and the description adds conditional behavior about response fields (authenticated:true, pending[], connect_url) that are not in the annotations. This goes beyond the structured data, though it could be more explicit about the lack of 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?

Two sentences, front-loaded with the primary action and then efficiently covering conditional cases. Every word earns its place—no redundancy or fluff.

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?

Covers the primary response scenarios and key fields, but does not detail the exact JSON structure beyond field names. For a simple read-only tool with no output schema, this is nearly complete; it could be slightly more explicit about whether any other response states exist.

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 schema coverage is 100% and the baseline is 4 per the rubric. The description focuses on return behavior, which is appropriate since no parameter semantics are 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?

Clearly states it 'Returns connection status and URLs' using a specific verb and resource. The description distinguishes this tool from siblings by focusing on status and URL output rather than actions like authentication or marketplace operations.

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 for when to use the tool by explaining the two response scenarios (all providers connected vs. missing credentials), implying its role as a health check. However, it does not explicitly name alternatives or state 'use instead of', so it stops short of full 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 only provide readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds significant behavioral context: invoke runs one-off without installing, returns connect/checkout links when needed, writes require workspace owner/admin, and search/describe flag installation status. It does not contradict annotations. It could mention that invoke may have side effects (e.g., running a tool) but the description already covers the one-off nature and auth/payment flows.

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 dense paragraph that is information-rich but not well structured. It front-loads the core flow but then covers many sub-features in a run-on manner. It could benefit from bullet points or clearer separation of the marketplace vs prompt library sections. However, every sentence adds value, so it's not verbose, just poorly formatted.

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, 23 params, no output schema), the description is quite complete. It covers the main flows, auth requirements, payment handling, and the prompt library. It doesn't explain return values (no output schema), but that's acceptable. It could mention the 'resume' action and the 'immediate' parameter, which are not explained, but overall it's sufficient for an agent to use the tool effectively.

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 key parameters implicitly: action (with all enum values explained), mcp_id, tool_id, arguments, prompt_* fields for the prompt library, and tier_slug for billing. It does not explicitly map every parameter (e.g., limit, query, immediate, conversation, report_context, request_details), but the action-based flow covers most usage. Given 23 parameters and 0% coverage, the description does a good job of explaining the main ones but leaves some 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 is the official mcp.ai marketplace catalog and execution platform, covering both discovery and running of MCPs. It distinguishes itself from siblings by explicitly naming the core flow (search → describe → invoke) and the prompt library sub-features, which differentiates it from tools like authenticate, connect, or tribunal_tjsp_segundo_grau_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 explicit guidance on when to use invoke vs install ('prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT'), and covers when to use search, describe, list_tools, subscribe/cancel, report_bug, request_mcp, and the prompt library functions. It also explains the flow for handling connect links and checkout links, which is actionable 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 indicate non-read-only, non-destructive, idempotent behavior. The description adds useful context by instructing users to include the conversation array for reproduction, but it does not disclose side effects such as whether a ticket is created or what happens after submission.

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 purpose and followed by a key usage instruction. There is no filler or redundant content.

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 and the description covers its primary purpose and the important reproduction instruction. However, with no output schema, it does not mention what the agent should expect after reporting (e.g., confirmation, response format), and the 'context' parameter remains unexplained.

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 (array with recent messages); 'message' and 'context' are left to their schema names, and no format or usage details are provided for them.

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 ('Report') and clear objects ('bug, missing feature, or send feedback'), making the tool's purpose immediately obvious. It also distinguishes itself from sibling tools like authenticate, toolkit_info, and tribunal_tjsp_segundo_grau_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 gives clear context for when to use the tool: to report a bug, request a missing feature, or send feedback. It does not explicitly name alternatives or exclusion cases, but there is no sibling tool with overlapping 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, fully covering the safety profile. The description adds no extra behavioral context, but given the strong annotation coverage, no further transparency is needed. The description does not contradict 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, concise sentence that states exactly what the tool does with no extraneous information. Perfectly 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?

For a simple, parameterless, read-only tool with comprehensive annotations, the description is fully adequate. There is no output schema, but the return value is implied ('versions') and doesn't require further detail. Complete for its intended purpose.

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?

This tool has zero parameters, so the description has no parameter semantics to explain. The schema already indicates an empty object, and the description correctly implies no configuration is required. The baseline of 4 for zero-param tools applies.

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 states a specific verb ('Show') and resource ('current MCP platform and adapter versions'), making the purpose clear. However, it does not explicitly distinguish from siblings like 'toolkit_info' or 'marketplace', though the resource is specific enough to avoid confusion.

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 a simple informational query with no side effects. While it doesn't explicitly state when to use this vs alternatives, the context of 'current versions' suggests a troubleshooting or environment-check scenario. No exclusions or alternatives are mentioned, but the purpose is unambiguous.

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 destructiveHint=false, so the safety profile is known. The description adds behavioral detail beyond those annotations by specifying exactly what data is returned (MCP installations, connection status, accounts, catalog tool counts). It does not contradict annotations, and it provides meaningful context about the tool's output.

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 efficiently conveys the tool's purpose and output. No word is wasted; it literally enumerates each piece of information returned, making it easy for an agent to grasp quickly.

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 absence of parameters and output schema, the description fully covers what the tool does and returns. The mention of 'catalog tools' is self-explanatory in context, and the sibling tools list does not suggest missing functionality. The description is complete for a simple read-only state inspection.

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 schema already provides complete coverage (100%). The description doesn't need to explain parameter semantics. Baseline for zero-param tools is 4, and no additional parameter information is necessary.

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' and enumerates the specific contents (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from siblings like show_version (version info) and connect (act of connecting) by focusing on the overall state rather than a single 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: it's a read-only tool for inspecting the toolkit state. However, it does not explicitly mention when to use this vs. alternatives (e.g., 'use this instead of show_version for connection details'). The context is clear enough that exclusions are not critical, but a more explicit pointer would have strengthened this dimension.

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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context beyond annotations: the prepaid credit/payment model, lack of platform credentials, official non-confidential nature of the data, and LGPD data-controller responsibility. 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 front-loaded with the core purpose and then adds relevant legal/commercial caveats in four concise sentences. No sentence is entirely wasted, though the LGPD clause could be seen as boilerplate.

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 10 optional parameters, no output schema, and no parameter-level descriptions, the tool is operationally complex, but the description omits query construction semantics, minimum required fields, pagination behavior, and result handling. It covers legal and payment context but not enough operational detail for reliable 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 does not explain any of the 10 parameters such as rg, cpf, oab, numero_processo, or pagina. It provides no guidance on which identifier is preferred, whether at least one is required, or how the parameters relate to each other, leaving the agent without enough semantic grounding.

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: 'Tribunal TJSP: Processos do 2º Grau, consulta em fonte oficial.' This names a specific verb (consulta), resource (TJSP 2º Grau processes), and scope (official source). It is clearly distinguishable from the generic sibling tools such as authenticate, marketplace, and report_bug.

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 operational context: no platform credentials are needed, queries are paid with prepaid credit, the data is the same publicly available to citizens, and the client is responsible for LGPD compliance. It does not explicitly name exclusions or alternatives, but the sibling tools are system-level and not competing consultation tools.

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