Tribunal TJSP: Certidão Criminal de 1º Grau

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

Annotations already mark the tool as idempotent and non-destructive. The description adds meaningful context: browser login, token copying, permanent vs session-only behavior, and no-args behavior. It does not mention the response after submitting a token, but it is transparent enough for an auth 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 front-loaded with the tool's purpose and then lays out the two login options compactly. It is slightly dense and mixes config advice with invocation instructions, but every sentence earns its place.

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 one optional parameter and no output schema, the description covers the login flow, token format, permanent vs session scoping, and no-args behavior. It could add success/failure response details, but an agent has enough information to invoke it correctly.

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 string parameter with no description, and the description fully compensates. It explains that token is a JWT, is only needed for session-only login, and that omitting it returns 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 this tool logs in to MCP.AI for IDE agents, with a specific browser-and-token flow. It distinguishes the auth purpose from sibling tools like 'connect' or 'marketplace' by detailing the two login modes.

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 gives explicit usage paths: permanent connection via config header, session-only login via token argument, and no-args to obtain the login link. However, it does not explicitly contrast this tool with sibling alternatives like 'connect', so it stops short of full when-to-use/alternatives 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 read-only and non-destructive, so the description adds value by specifying the two possible return states (authenticated:true with empty pending, or connect_url). This extra detail helps the agent understand what to expect 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 concise (two sentences) and front-loaded with the primary purpose ('Returns connection status and URLs'). Every sentence provides necessary detail without 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?

With no parameters Recognized and annotations covering safety, the description adequately explains the tool's behavior for both connection states. It is complete for a status-checking tool with no output schema.

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 parametersas shown in the input schema, so there are no parameter semantics to explain. The description correctly omits parameter details; the baseline for 0 params is 4, and no additional info 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 that the tool returns connection status and URLs, with specific behaviors for connected vs. missing credentials. It distinguishes itself from sibling tools like authenticate and marketplace by focusing solely on status checking.

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 checking connection status but does not explicitly state when to use this tool vs. alternatives (e.g., authenticate). It gives context on the two possible outcomes but no direct guidance on when to choose this over siblings.

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 readOnlyHint=false, but the description goes far beyond annotations: it explains that invoke runs tools even when the MCP is not installed, that it doesn't bloat the toolkit, and that writes require workspace owner/admin. It also details the difference between one-off invoke and permanent install, and the implications for future sessions. This transparency clearly exceeds 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 quite long but packed with essential information. It is well-structured with a logical flow from discovery to execution, and covers the prompt library separately. While every sentence adds value, the length is borderline; however, given the tool's complexity (23 parameters, 14 actions, multiple subsystems), the length is justified. It could be slightly more concise but is not wasteful.

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 high complexity (23 parameters, 14 actions, no output schema, no parameter descriptions), this description is remarkably complete. It explains the entire workflow, the distinction between one-off invoke and permanent install, auth/payment handling, the prompt library subsystem, workspace permissions, and the installed_in_toolkit vs installed_in_workspace flags. There is no output schema to explain, and the description covers all major behavioral aspects. This is as complete as one could expect for such a multi-faceted 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?

With 0% schema description coverage, the description fully compensates by explaining the semantic roles of key parameters: action controls the action type, mcp_id identifies the MCP, tool_id selects the tool, message contains the prompt, arguments carries invocation args, and prompt_* fields belong to the prompt library. It also explains the meaning of action values and the interplay between parameters (e.g., search needs query, describe needs mcp_id, invoke needs tool_id and arguments). This compensates for the lack of parameter descriptions in 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 that this is 'the official mcp.ai marketplace' for discovering and running MCPs. It specifies the core workflow (action=search discovers MCPs, describe returns profiles, invoke runs tools), and distinguishes itself from sibling tools like authenticate and toolkit_info. The purpose is explicit and covers the catalog and execution capabilities.

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: when to use search, describe, invoke, install, and list_tools, with explicit recommendations like 'prefer invoke for a single/occasional use' and 'use install only to make an MCP PERMANENT.' It also explains the behavior for auth and payment scenarios ('invoke returns a connect link' if credentials needed, 'checkout/top-up link' if wallet empty). This is exemplary guidance for choosing among the 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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds a behavioral hint about including the conversation array for reproduction, but it doesn't disclose side effects like what happens after reporting (e.g., ticket creation, external transmission). This is acceptable given the annotations, 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 sentence plus a directive. It is front-loaded with the purpose and includes a specific instruction for the conversation parameter. Every word contributes; no fluff or 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?

The tool is simple with no output schema, no nested objects, and only three parameters (one required). The description covers the main purpose and the key parameter (conversation), but doesn't mention the response or what happens after submission. Given the low complexity and existing annotations, it is largely complete, with minor gaps for the context parameter.

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 explain parameters. It explicitly mentions the conversation parameter ('Include the conversation array') and implies message via 'Report a bug...' but does not explain the context parameter (default empty string). It partially compensates but leaves one parameter undefined.

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 a bug, missing feature, or sending feedback. It specifies the resource (bug/feature/feedback) and distinguishes it from unrelated siblings like authenticate or show_version. The instruction to include the conversation array for reproduction adds specificity.

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 the tool: when there's a bug, missing feature, or feedback to send. It doesn't explicitly exclude alternatives, but the sibling tools are unrelated, so there is clear context for use. No explicit when-not guidance, but it's not needed given the clear domain.

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, covering the safety profile. The description adds only the basic behavior (showing versions) without additional details like output format or potential scope. It does not contradict annotations but adds minimal context beyond 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 a single, concise sentence that immediately conveys the tool's purpose. There is zero waste, and the most important information is 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?

Given the tool's simplicity (no parameters, no output schema, and comprehensive safety annotations), this description is fully complete. It specifies exactly what the tool does, and nothing more is needed for an agent to invoke it correctly.

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 baseline is 4. The description does not need to explain parameters since there are none. The schema coverage is 100% effectively, and no parameter information 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 uses a specific verb ('Show') and specifies the resource ('current MCP platform and adapter versions'), making its purpose unmistakable. It clearly distinguishes itself from sibling tools like 'authenticate' or 'marketplace', which serve entirely different functions.

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 usage is implicitly clear: use when you need version information for the MCP platform or adapter. While not explicitly stating when to avoid using it, the sibling tools are unrelated, so there is no ambiguity. The context alone provides adequate 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context about the exact content returned (installed MCPs, connection status, accounts, catalog tool counts), which is behavior beyond the annotations. No contradictions found.

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?

Description is a single, efficient sentence that front-loads the action ('Returns the current toolkit state') then lists the specific components returned. No wasted words, perfectly concise while conveying all necessary 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?

For a zero-parameter, read-only status tool, the description fully enumerates the return content (installed MCPs, connection status, accounts, catalog tool counts). No output schema exists, but the description gives a clear mental model of the response. Given the low complexity and strong annotations, the description 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?

There are zero parameters, so the schema provides no parameter details. The baseline for 0 parameters is 4, and the description does not need to explain parameters since none exist. The description focuses on the output, which 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?

Description clearly states the tool returns the current toolkit state with specific details (installed MCPs, connection status, accounts, catalog tool counts). It uses a specific verb 'Returns' and a precise resource, distinguishing it clearly from sibling tools like authenticate, connect, and marketplace 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 clearly communicates the tool's purpose and output, implying use for checking toolkit status. It doesn't explicitly mention when not to use it or contrast with alternatives, but given the sibling list, it is self-evident that this is the status inspection tool and others are for action-oriented tasks. Lacks explicit exclusions, but context is clear.

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. The description adds value by explaining the payment model (prepaid credit), that the platform hosts the service without requiring platform credentials, and that the data is non-confidential and subject to LGPD compliance. This goes beyond annotations, though it does not cover error handling or response format.

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, each carrying distinct information: purpose, payment/hosting details, and legal responsibility. It is front-loaded with the core purpose and avoids fluff. However, it could be more concise while retaining the legal context; it is not padded but could be slightly streamlined.

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 high complexity (13 parameters, no output schema, no parameter docs), the description is incomplete. It provides legal and payment context but does not explain the request parameters or the nature of the response. Even with annotations, the agent cannot reliably construct a valid request without more parameter semantics. The lack of output schema and parameter guidance makes this insufficient.

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 13 parameters with zero description coverage. The description does not explain any parameter (email, finalidade, cpf, etc.) and only vaguely mentions 'finalidade legítima' in the LGPD context. It fails to compensate for the low schema coverage, leaving the agent without clues about how to populate the 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 clearly states the tool's purpose: consulting a 'Certidão Criminal de 1º Grau' (criminal certificate) from the TJSP (São Paulo court). It specifies it is a consultation from an official source, distinguishing it from generic sibling tools like authenticate or marketplace. The verb 'consultar' in the tool name is reinforced by the description, making action and resource 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 notes that payment is via prepaid credit and that the data is not confidential, but it does not provide explicit when-to-use vs. alternatives. It implies usage for requesting criminal certificates but lacks clear exclusions or comparison with other tools. Context is given (official source, LGPD responsibility), but no formal guidance.

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