Tribunal TJSP: Cadastro de Pedido de Certidão

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

Annotations already provide idempotentHint, readOnlyHint=false, destructiveHint=false. The description adds valuable behavioral context: a token pasted via the tool is 'session-only' while config-based auth is 'permanent, non-expiring', and calling with no args yields a login link. It does not detail failure modes or state changes, but the added session-vs-permanent distinction exceeds the annotation baseline.

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 about 70 words, structured with 'Best:' and 'Or' to separate the two usage paths. It is front-loaded with the core login flow and avoids irrelevant detail. Slightly longer than necessary due to the opening product context ('MCP.AI for IDE agents'), but each sentence contributes useful 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?

Given a simple one-parameter tool with no output schema, the description covers the main workflows: obtaining a link with no args, using a pasted JWT for session-only auth, and the recommended config-header approach. It does not explicitly state what the tool returns when a token is provided or how errors are surfaced, but for an authentication helper this is a minor gap.

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 token parameter with 0% description coverage, so the description carries full responsibility. It explicitly defines token as a JWT to be pasted by the user, explains when to include it (after user pastes) and when to omit it (to get the link). This fully compensates for the schema's lack of parameter documentation.

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 the user for MCP.AI IDE agents by logging in via browser and copying an access token. It specifies the exact action ('log in in the browser, copy the access token') and distinguishes between two modes (permanent config vs session-only), making it unambiguous and distinct from sibling tools.

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 explicit when-to-use guidance for its two modes: 'Best' for permanent non-expiring config and 'Or' for session-only login. It explains exactly how to call with or without the token. However, it does not mention alternatives among sibling tools or when not to use authenticate at all, so it lacks a full exclusionary contrast.

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 and idempotentHint, lowering the bar. The description adds specific return value behavior (authenticated flag, pending array, connect_url) beyond annotations, providing useful context for what the tool does 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?

The description is two sentences, front-loaded with the main purpose, and then explains the two states concisely. Every word earns its place; no 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 output schema, the description carries the burden of explaining output. It covers the key fields (authenticated, pending, connect_url) in both states. It lacks details about other possible fields or edge cases, but for a simple status tool it's sufficient. Could be slightly more explicit about when to use this vs authenticate.

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, and schema coverage is 100% (empty schema). Baseline for 0 params is 4, and the description doesn't need to explain any parameters. It effectively describes the tool's behavior, which is sufficient.

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 connection status and URLs, and specifies two distinct states (all connected vs credentials missing). This is specific and distinct from siblings like authenticate, as it's purely a status/URL retrieval tool.

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 doesn't explicitly mention when to use it instead of authenticate or other siblings. It provides behavioral context (connected vs missing credentials) but no explicit when-to-use guidance or 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?

Beyond annotations (readOnlyHint:false, destructiveHint:false), the description discloses critical behaviors: invoke runs one-off without adding to toolkit, auth and billing return links, writes require owner/admin, and installed status flags are available. This goes well beyond the minimal annotation set and fully informs the agent about side effects and prerequisites.

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 that covers the workflow, permissions, auth, billing, and prompt library. While every sentence carries useful information, the block format and length reduce readability. Front-loading the definition and flow helps, but a structured list or separation of prompt library would improve 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 high complexity (23 params, 14 actions, no output schema), the description thoroughly covers the main flow, return types (e.g., describe returns full profile, invoke returns connect/checkout links), permissions, and the prompt library. It explains the distinction between installed_in_toolkit and workspace and includes edge cases like needing login or wallet top-up. This is complete for a tool of this scope.

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 for 23 unnamed parameters. It does explain the 'action' enum conceptually (search, describe, invoke, install, etc.) and refers to tool_id and arguments in the flow, but it does not define parameters like limit, mcp_id, immediate, tier_slug, prompt_* fields, or cancel_reason. Given the high parameter count and zero coverage, this 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 opens with a clear statement: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It further specifies capability requests ('find an MCP that does X', 'consulta um CPF') and outlines a concrete search→describe→invoke flow. This distinguishes it from sibling tools like authenticate or toolkit_info, which are not about marketplace discovery.

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 gives usage rules: 'Use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use.' It also explains when to use list_tools, subscribe/cancel, report_bug, and request_mcp. The core flow is laid out with action=search → describe → invoke, and the prompt library actions are segregated. This provides clear when-to-use guidance versus 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?

The description does not contradict the annotations (idempotent, non-destructive). It adds a note about including conversation for reproduction, but does not disclose side effects or processing details beyond that.

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, using two short sentences with no extraneous 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?

The description lacks explanations for most parameters and does not mention outcome or error handling, though the tool is relatively simple.

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?

Only the 'conversation' parameter is partially explained (as an array of recent messages). The required 'message' and optional 'context' are not described, and schema coverage is 0%.

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: reporting bugs, missing features, or sending feedback. It is distinct from the sibling tools which handle authentication, connectivity, marketplace, etc.

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 this tool (when reporting a bug or providing feedback) but does not explicitly mention alternatives or exclusions.

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, which cover safety. The description adds that versions pertain to 'MCP platform and adapter,' but it doesn't disclose potential side effects like network requests or output specifics. It aligns with annotations, so no contradiction, but the description adds minimal behavioral context 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?

A single, well-formed sentence that immediately conveys the purpose. No unnecessary words or repetition, making it optimally concise.

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 trivial version-check tool with no parameters and no output schema, the description is fully sufficient. It could theoretically clarify what 'adapter' refers to, but such detail is not necessary for an agent to invoke the tool 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?

With zero parameters and schema coverage at 100% (vacuously), the description didn't need to explain parameters. The baseline of 4 for zero-parameter tools applies, and the description doesn't detract from that.

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 shows 'the current MCP platform and adapter versions,' which is a specific verb-resource pairing. This distinguishes it from sibling tools like 'toolkit_info' or 'authenticate' that 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?

There is no explicit guidance on when to use this tool versus alternatives, and no mention of alternatives or exclusions. For a trivial version-query tool, usage is self-evident, but the description relies on implication rather than stating context or exclusions.

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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description adds no new behavioral context (e.g., no auth requirements, no rate limits, no side effects). It only restates the purpose (returns state) without enriching what the agent knows beyond the structured metadata.

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, tight sentence that front-loads the verb ('Returns') and clearly enumerates the output contents. Every word contributes to the meaning; there is no filler 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?

For a simple read-only tool with no parameters and no output schema, the description fully explains what the return value contains (installed MCPs, connection status, accounts, catalog tool counts). It does not mention edge cases (e.g., empty state), but such details are likely unnecessary for a state inspection tool. The description is adequate for the 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?

There are zero parameters, and the schema is empty. The baseline for 0 params is 4, and the description correctly does not attempt to add parameter details. It adds no extra semantic value for parameters, but that is not needed since none exist.

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: it returns the current toolkit state, enumerating specific components (installed MCPs, connection status, accounts, catalog tool counts). This specific verb and resource differentiation distinguishes it from siblings like show_version (version info) and authenticate/connect (auth flows).

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 explicit guidance on when to use this tool versus alternatives. It does not state that it is the go-to for state inspection, nor does it exclude cases where it might be unnecessary (e.g., when connectivity is already known). No alternatives are mentioned, so the agent must infer usage from the name and description alone.

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 mark this as readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds value by noting that the query is against official public sources, has LGPD implications, and is hosted on the platform with no credentials, pay-per-query credit system. It clarifies the agent's responsibility regarding data privacy (controller = client, legitimate purpose). This gives behavioral context beyond annotations, helping the agent understand implications of the query.

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 solid paragraph that's efficiently written, covering the essential points: what it does, where data comes from, operational details (paid per query, no credentials), and legal note (LGPD). Though a bit long, it's well-structured and each sentence adds value. Could be broken into a few sentences but flows coherently without being overly verbose.

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 provides adequate context about the query source and legality, but several important details are missing: no explanation of what is done with the queried data (e.g., how results are returned), no mention of required input formats for parameters, and no specifics on which fields are mandatory beyond 'modelo' and 'email_envio'. For a tool with 14 parameters and no additional schema documentation, the description does not fully compensate for the lack of parameter details or 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 schema has 14 parameters with 0% description coverage. The description does not explain any parameters beyond mentioning 'modelo' and 'email_envio' implicitly. It doesn't clarify what 'modelo' (model/format) means in this context, nor the expected format for fields like 'birthdate' or 'naturalidade_uf'. Given the ambiguity, the description fails to compensate for the schema's lack of parameter documentation.

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 purpose is clearly described as consulting the registration of a certificate request at TJSP. It includes the scope (Brazilian official sources, same as available to citizens) and its directness to the correct source. While the exact operation is somewhat embedded in the tool name, the description provides valuable context that the data is from official Brazilian sources and not confidential, which helps disambiguate it from other possible operations like creating or canceling a certificate request.

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 this is for use with official Brazilian sources, but doesn't explicitly compare with alternatives. However, the statement about being for legitimate purposes (LGPD) and the no-credential, pay-per-query model gives context on when it's appropriate to use. Without listing alternative tools, it provides clarity that this handles public, non-confidential, official data queries, which implicitly guides usage.

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