Tribunal TJSP: Download da Certidão de 1º Grau

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

The description adds meaningful behavior beyond the annotations by explaining that config-based auth is permanent and non-expiring, while token-based auth is session-only. Nothing in the description contradicts the annotations; the idempotent, non-destructive, non-read-only hints are consistent with the described auth flow.

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 compact and front-loaded with the key action, then explains the two authentication flows in sequence. The opening phrase "MCP.AI for IDE agents" is a bit of context clutter, but the rest of the description is efficient and useful.

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 explains the main flows and the no-args link behavior, which is important since there is no output schema to clarify return values. However, it does not describe what the tool actually returns when a token is passed, nor how errors or invalid/expired JWTs are surfaced. Given the tool's authentication complexity, this is a meaningful completeness 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 `token` parameter has no schema description, but the tool description compensates reasonably well by giving the exact call shape `{ token: "<jwt>" }` and explaining that it should be called after the user pastes the JWT. It also makes clear the parameter is optional by describing the no-args flow. More detail about token format, expiration, or failed-token behavior is not covered.

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 identifies authentication as its purpose and explains how to use it: log in through the browser, copy a token, or get a link with no arguments. However, it does not explicitly differentiate itself from the sibling `connect` tool, so it falls just short of full sibling-level clarity.

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 usage guidance: add the token to the server config as a permanent `Authorization: Bearer <token>` header, or pass the token for a session-only login, or call with no args to receive the link. It does not explicitly state when to avoid this tool or choose one of the sibling tools instead.

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 readOnly, idempotent, and non-destructive behavior. The description adds meaningful conditional behavior: the exact response shape for connected versus missing-credential states. No contradiction with 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 focused sentences deliver the main purpose first, then conditional response details. Every clause adds value and there is 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?

With zero parameters, rich annotations, and no output schema, the description fully explains what the agent can expect from the tool. The conditional states are enough for an agent to select and interpret results 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 and the schema is fully covered at 100%, so parameter-level semantics are not needed. The description appropriately focuses on output behavior instead.

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 'Returns connection status and URLs,' which is a specific verb+resource statement. It clearly distinguishes this status-checking tool from siblings like authenticate and 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 implies when to use the tool: check connection status, especially when credentials may be missing. However, it does not explicitly compare against alternatives like authenticate or state 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?

Despite annotations being minimal (readOnlyHint false, openWorldHint true), the description discloses significant behavioral traits: invoke works even without installation, returns connect/checkout links for auth/payment, and notes that install/uninstall are write actions requiring owner/admin. It also separates the prompt library as a distinct capability, providing context beyond annotations without contradiction.

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 long, which is appropriate given the tool's complexity, but it is a single dense paragraph that could benefit from better structure (e.g., breaking out the prompt library into a separate section). Still, every sentence adds value and it front-loads the core purpose, so it's concise relative to the information needed.

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 remarkably complete. It covers the core flow, invocation behavior, authentication and payment handling, permission requirements, and the separate prompt library. It omits some minor details (error handling, return formats) but provides enough for an agent to select and use the tool correctly in most scenarios.

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 23 parameters and 0% schema description coverage, the description compensates by explaining the key parameter 'action' and its enum values within the flow, plus how tool_id is used in invoke. However, it does not individually describe all parameters (e.g., arguments, immediate, tier_slug, prompt_*), though the workflow it outlines gives contextual meaning to the most critical ones, making it a strong but not exhaustive compensation.

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 identifies the tool as the official mcp.ai marketplace—a catalog and execution platform for MCPs. It states a specific verb+resource (search/describe/invoke) and distinguishes itself from sibling tools like authenticate, connect, and report_bug by outlining its comprehensive role covering both discovery and running of MCPs.

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 usage guidance: it details the core flow (search → describe → invoke), when to use invoke vs install (one-off vs permanent), and references other actions like list_tools, subscribe/cancel, and the prompt library (search_prompts, get_prompt, publish_prompt). It also notes that writes require owner/admin, giving clear context on alternatives and constraints.

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 the tool is idempotent and non-destructive, so the description adds limited behavioral detail. It mentions including conversation for reproduction, hinting at context usage, but does not explain side effects or outcomes, keeping transparency modest.

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 concise sentences with no extraneous words. It efficiently communicates the core action and a key requirement, making it easy to parse.

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 is largely sufficient: it states purpose and input guidance. However, it omits details like expected return values or error handling, but given the lack of output schema and low complexity, this is acceptable.

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 no descriptions, but the description explains the purpose of the 'conversation' parameter (to aid reproduction) and implies 'message' is the content of the report. It does not clarify 'context', but this partial coverage improves understanding.

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 feedback, which is a distinct function compared to sibling tools like authenticate or show_version. It also specifies a required action (include conversation) that clarifies its 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 when to use the tool (for bug reports or feedback) but does not explicitly contrast with alternatives. It provides guidance on how to use it (include conversation array), which is helpful though not exhaustive for a usage decision.

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 that the tool is read-only, idempotent, and non-destructive. The description adds no further behavioral details (e.g., response format or side effects). Since annotations cover the core traits, the description doesn't extend transparency beyond what is already declared.

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, direct sentence with no redundancy or extraneous details. It conveys the essential purpose efficiently.

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 fully states what the tool does given the lack of parameters and output schema. It could optionally specify the output format (e.g., exact fields), but the current phrasing is sufficient for a straightforward version-checking 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?

The tool has zero parameters, so schema coverage is effectively 100%. The description adds no parameter-specific meaning because there are none to explain. This matches the baseline for tools with complete schema coverage and no additional parameter info.

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 action ('Show') and the specific resource ('current MCP platform and adapter versions'), which is distinct from sibling tools like 'authenticate' or 'report_bug'. It unambiguously communicates the tool's function.

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 explicitly state when to use this tool versus alternatives. While the purpose implies it is for retrieving version information, it lacks guidance on scenarios (e.g., checking compatibility) or why it might be preferred over 'toolkit_info'.

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 safe read-only nature is covered. The description adds specific behavioral context by listing what the returned state includes (installed MCPs, connection status, accounts, tool counts), which goes beyond the annotations and gives a clear picture of the tool's output semantics.

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 core purpose and then lists the specific data returned. Every part is informative, with 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?

Despite having no output schema, the description fully explains what the tool returns (state details). With no parameters and no side effects, and given the thorough annotations, the description is complete for an agent to correctly invoke and interpret the 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?

The tool has zero parameters, and the schema describes an empty object with 100% coverage. Per the instructions, the baseline is 4 for zero-parameter tools, and the description does not need to add parameter details. It correctly focuses on the return contents.

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 ('returns') and resource ('toolkit state') and then enumerates the exact contents: installed MCPs, connection status, accounts, and catalog tool counts. This clearly distinguishes it from sibling tools like connect or authenticate, 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 implies usage (when you need to inspect toolkit state), and the sibling tools are clearly different (authentication, connection, bug reporting, etc.). However, it does not explicitly state when not to use it or mention alternatives, so it falls short of a perfect 5.

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, and the description adds meaningful context: no platform credentials are needed, each query is paid for with prepaid credit, the data is public/non-confidential, and the client is the LGPD data controller. This goes beyond the structured annotations, though it does not describe the exact return format or failure behavior.

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 and front-loaded with the core purpose. The subsequent sentences about payment, official sources, and LGPD responsibility add relevant operational and compliance context without excessive verbosity.

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 covers the tool's purpose and some operational context, but with no output schema and no parameter documentation, the agent is left without key details: which inputs are valid, whether CPF/CNPJ are alternatives or required together, and what the downloaded certificate looks like. The description is not complete enough for reliable tool invocation.

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 0% description coverage and the description does not explain any of the three parameters (cpf, cnpj, numero_pedido). It does not state which identifiers are required, how they relate to the certificate, or the role of numero_pedido. Since the description must compensate for the lack of schema-level parameter detail and does not, this dimension is severely lacking.

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 action ('Download da Certidão de 1º Grau') and the resource ('Tribunal TJSP'), making the tool's purpose unambiguous. It also distinguishes itself from the unrelated sibling tools by naming the specific court and certificate type.

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 useful context: it is for TJSP first-degree certificates, queries official sources, requires prepaid credit, and does not require platform credentials. It does not explicitly say when not to use it or name alternatives, so it stops short of full usage-guideline coverage.

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