Tribunal TJSC: Pedido de Certidão

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

The description discloses that the tool can establish a permanent or session-only connection, and mentions that calling without args returns a login link. This gives some insight into behavior beyond annotations. However, it does not explicitly mention side effects like modifying server configuration or creating a token, and it does not contradict the idempotentHint annotation.

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 verbose with extraneous phrases like 'MCP.AI for IDE agents (Cursor, etc.)' and 'Best:' and 'Or paste it here'. While it provides necessary instructions, it could be streamlined to be more direct and 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?

Given the simple schema and no output schema, the description covers the essential aspects: what it does, how to use it, and the parameter. It also mentions the two modes. It lacks comparison with sibling tools, but that may not be necessary for this simple authentication tool. Overall, it 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?

The schema has a single optional 'token' parameter. The description explains that it is the access token and that it can be omitted to generate a login link. This fully clarifies the parameter's meaning and optionality, leaving no ambiguity.

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 handles authentication, either by accepting a token or returning a login link. It provides concrete usage patterns (calling with token or no args) which makes the purpose clear despite some superfluous context about MCP.AI and IDE agents.

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 guidance on when to use each approach: providing a token for a permanent connection or generating a link for session-only login. It also mentions the best practice of adding the token to the server's config. However, it does not explicitly compare with alternative tools, so it's not fully explicit about when not to use it.

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 convey read-only, idempotent, and non-destructive behavior. The description adds useful behavioral detail by specifying the exact return states and content, such as authenticated:true, empty pending[], and connect_url for the toolkit and per-install URLs, going 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 two sentences, front-loaded with the core purpose ('Returns connection status and URLs') and immediately provides conditional details. Every sentence adds value with no redundancy or filler.

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 parameterless, read-only status tool with no output schema, the description adequately explains expected return values for the main states. It covers both connected and missing-credential scenarios, making it complete for an agent to invoke 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?

The tool has zero parameters, so the schema is fully covered. The description does not need to explain parameters and correctly focuses on return behavior; baseline 4 applies 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 clearly states the tool returns connection status and URLs, and includes specific conditional behavior (authenticated:true vs connect_url). It distinguishes itself from siblings like authenticate by focusing on status reporting rather than authentication actions, though it does not explicitly name alternatives.

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 indicates when to use the tool: to check connection status, with concrete examples of connected versus missing-credential states. It does not explicitly exclude use cases or reference sibling tools, but the intended context is unambiguous for a status-checking utility.

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, openWorldHint=true, and idempotentHint=false but do not contradict the description. The description goes far beyond annotations by detailing side effects: invoke runs tools even if MCP is not installed, returns connect links for missing credentials, checkout links for empty wallet, and explains that install makes tools permanent. It also reveals that invoke itself performs a one-off install, adding context not visible in 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, dense 200+ word paragraph without bullet points or sections. While every sentence adds value, it is not concise and is hard to scan. It would benefit from segmentation by action group (MCP actions, prompt actions, admin/feedback actions). The length is justified by complexity, but the lack of structure reduces readability and understandability.

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 high complexity (23 params, 14 actions, no output schema), the description provides a thorough overview of the main flows and edge cases (credential/payment handling, permissions, permanent vs one-off installs). It covers all major action categories and retrieval of MCP profiles. It lacks explicit detail on some parameters and return formats for all actions, but overall it is sufficient for an agent to operate effectively. A 4 is justified.

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 meaning of key parameters indirectly through the flow: action enum values (search, describe, install, etc.), mcp_id, tool_id, arguments, and prompt-related fields (search_prompts, get_prompt, publish_prompt). However, many parameters like cancel_reason, cancel_comment, report_context, request_details, immediate, tier_slug, prompt_targets are not explicitly described, though their names are mostly self-explanatory. The description adds value but doesn't fully cover all 23 parameters, so a 4 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 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 then outlines the core flow (search → describe → invoke) and distinguishes itself from sibling tools like authenticate, connect, and show_version. It is specific about the resource (MCPs and prompts) and the actions performed, making its purpose unmistakable.

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 instructs when to use invoke vs install ('prefer invoke for a single/occasional use', 'use install only to make an MCP PERMANENT'), when to use search/describe, when list_tools is appropriate, and even covers subscribe/cancel and prompt actions. It also notes permission requirements ('Writes ... require workspace owner/admin') and behavior when credentials or payment are needed. This is exemplary guidance for an agent.

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 (idempotentHint=true) are present)Skip the behavioral disclosure does not contradict them字号. The description adds that the conversation array is needed for reproduction, which is helpful, but does not disclose any other behavioral traits like side effects or authentication needs. Since annotations are availableknowledge, this is acceptable but not outstanding.

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 clearly state purpose and the key parameter instruction. No fluff, 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?

Given it's a simple feedback tool with only one required parameter summary说明，the description covers the essentials. It does not explain output or side effects, but for this tool type, it's adequate.

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 has 0% description coverage, so the description must compensate. It explains 'conversation' as for reproduction, and implies 'message' is the feedback text, but 'context' is not explained. This is partial compensation, so a middle score 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's purpose: 'Report a bug, missing feature, or send feedback.' It uses a specific verb and resource, 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 says to include the conversation array with recent messages for reproduction, which provides context on how to use the tool. It does not explicitly state when not to use it or alternatives, but the purpose is clear enough to distinguish it from 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the specific scoping to 'MCP platform and adapter' versions. For a trivial read-only tool there is little behavior to disclose, and the description is consistent with 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, tightly worded sentence that starts with the action verb ('Show') and wastes no words. Every word adds meaning, and the sentence is appropriately sized for the tool's trivial complexity.

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 version-info tool with annotations covering its safety profile, the description is complete. There is no output schema, so no return-value documentation is expected.

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 takes zero parameters with 100% schema coverage by default. There is no parameter information for the description to add, so it carries no burden here.

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 a specific resource ('current MCP platform and adapter versions'), making the tool's function immediately clear. It distinguishes itself from siblings by scoping specifically to MCP platform and adapter versions, which differs from broader tools like `toolkit_info`.

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 does not give explicit when-to-use guidance or name alternatives like `toolkit_info`. However, the usage is implied by the simple, self-evident purpose of retrieving version information, so an agent can reasonably infer when to invoke it.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds behavioral transparency by specifying exactly what is read and returned, including connection status and account associations, which goes beyond the bare 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, well-structured sentence that front-loads the purpose and uses a colon to enumerate the result contents. There is no wasted wording, and every clause adds meaningful 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 with no output schema, this description is complete. It lists all major result categories in sufficient detail for an agent to decide whether to call it and what to expect from its response.

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 the schema coverage is 100%, so there are no parameter ambiguities. The description does not need to explain parameters; the baseline of 4 is appropriate because the tool is trivially simple to invoke.

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 the specific verb 'Returns' and clearly names the resource ('current toolkit state'), then enumerates the exact contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This fully distinguishes the tool's purpose from siblings like 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 makes the usage context clear: call this tool when you need an overview of the current toolkit state, including MCP connections and accounts. It does not explicitly mention alternative tools or when not to use it, but the purpose is specific enough that the intended use is evident.

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 unique behavioral context: payment per query via prepaid credit, data is public/official, and the client is the LGPD data controller. This enriches transparency 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 three sentences, each adding distinct value: purpose, payment/hosting model, and legal/data scope. No filler or redundancy; front-loaded with the core action.

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 complex tool with 18 parameters and no output schema, the description is severely under-specified. It omits parameter explanations, expected response format, and any procedural details beyond 'no platform credentials'. The legal disclaimer and data source info are helpful but 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?

With 18 parameters and 0% schema description coverage, the description adds no meaning to any parameter. Required fields like instancia, tipo, nome, uf, municipio, and email are completely unexplained, leaving the agent to guess their 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 queries official TJSC certificate data ('consulta em fonte oficial'). It distinguishes from sibling tools which are platform-level (authenticate, connect, marketplace), but the phrase 'Pedido de Certidão' is slightly ambiguous as it could imply ordering rather than consulting.

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 (prepaid credit, no platform credentials, official Brazilian sources) but does not explicitly state when to use this tool versus alternatives. Sibling tools are generic platform utilities, so the distinction is implicit but not articulated.

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