Tribunal STJ: Certidão Negativa

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

The description adds behavior beyond annotations: it contrasts permanent vs session-only login, explains the browser login prerequisite, and describes the effect of passing or omitting the token. This complements the idempotentHint and destructiveHint 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 dense and front-loaded, but the opening 'MCP.AI for IDE agents (Cursor, etc.)' is unnecessary context. Otherwise, every clause carries essential information, making it appropriately sized.

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, the description covers both invocation modes, the user interaction needed (browser login), and the durability of each method. It is complete enough for an agent to use correctly without additional information.

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 only parameter 'token' is fully explained: it is an optional JWT to paste for session login, and omitting it returns the login link. This adds crucial meaning beyond the bare string type 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 the tool authenticates the agent to the server, with specific actions: log in via browser, copy token, and use it either via config header or session token. It distinguishes the two methods and the overall purpose is 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?

Explicit guidance is provided: config header is best for permanent non-expiring connection, while pasting the token is for session-only login. It also explains when to call with no args (to get link) versus with token, giving clear decision criteria.

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 behavioral context about the two possible states (authenticated vs missing credentials) and what URLs are returned. It does not describe any side effects or additional behaviors, but with annotations covering the safety aspects, this is adequate.

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 every sentence adds value. It is concise and well-structured, with no wasted words.

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 has no parameters, no output schema, and annotations cover the safety profile, the description is fairly complete. It explains the two possible states and what URLs are returned. It could mention the format of the URLs or the structure of the response, but for a simple status tool, this is sufficient. The sibling tools like authenticate and toolkit_info might overlap, but the description is adequate for the tool's simplicity.

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 provides no parameter semantics. The description explains the output behavior in different states, which is the main semantic content. Since there are no parameters, the description does not need to add parameter meaning, and it provides useful context about the return values. Baseline 4 is appropriate for zero-parameter 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 distinguishes between the authenticated state and missing credentials state. It is specific about the resource (connection status) and the output (authenticated flag, pending array, connect URLs). It does not explicitly differentiate from siblings, but the purpose is clear.

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 it (to check connection status and get URLs when credentials are missing), but it does not explicitly state when not to use it or mention alternatives. Given the sibling tools like authenticate and toolkit_info, some guidance on when to use connect vs authenticate would be helpful, but the context is reasonably 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 are minimal (readOnlyHint=false, openWorldHint=true), so the description carries the disclosure burden and excels: it openly states invoke can run tools without install, returns connect links for missing credentials, returns checkout/top-up links for empty wallets (with a retry directive), and that writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin. 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?

The description is a single dense wall of text with no line breaks, bullets, or section headers despite covering 14 distinct actions across two domains (MCPs and the prompt library). It lacks front-loading — the key 'invoke works without install' insight is buried mid-paragraph. Highly informative but poorly structured for agent parsing.

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-action enum, no output schema), the description is remarkably thorough: it covers the full MCP lifecycle (search, describe, invoke, install, billing via subscribe/cancel, report_bug, request_mcp) plus the prompt library, and notes installed_in_toolkit vs installed_in_workspace flags. Some return-format detail is absent given no output schema, and the density hurts extractability, but coverage is essentially 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?

With 0% schema description coverage and 23 parameters, the description carries full responsibility and explains the most important ones in context: action (all 14 enum values are covered by the workflow narrative), mcp_id, tool_id, arguments, tier_slug (pricing), and the prompt_* family (prompt_body, prompt_vars, prompt_title, prompt_description, prompt_category, prompt_targets). However, several params remain unexplained (limit, query, message, immediate, conversation, request_name, request_details, cancel_reason/cancel_comment, report_context), so it doesn't fully compensate for the coverage 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 clearly states the tool is the official MCP marketplace — the in-platform catalog of MCP/tools and the way to run them. It names specific capabilities ('find an MCP that does X', 'consulta um CPF') and lays out the core search → describe → invoke flow, which distinguishes it from sibling tools like tribunal_stj_certidao_negativa_consultar (a specific MCP tool) and toolkit_info (which lists current state).

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 strong contextual guidance: when to use invoke (one-off, works without install) vs install (permanent toolkit addition), the recommended discovery workflow, and the prompt-library path (search_prompts/get_prompt/publish_prompt) vs MCP path. It lacks explicit mentions of when NOT to use the tool or named alternatives among siblings, but the prefer-invoke-over-install recommendation is clear enough.

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 adds behavioral context by instructing to include the conversation array for reproduction. Since annotations already indicate idempotent and non-destructive behavior, this additional guidance is helpful 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 two concise sentences with no superfluous words. It efficiently conveys the action and a key requirement.

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 sufficient: it states the purpose and the necessary input detail. Lack of output schema is acceptable as return values are not mentioned.

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 description explains the 'conversation' parameter but leaves 'context' and 'message' partially undefined. With zero schema descriptions, it provides some but not complete parameter clarity.

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.' This is a specific verb-resource pair that distinguishes it from sibling tools like authenticate or 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 implies usage for reporting issues but does not explicitly contrast with alternatives or state when it should be preferred. It gives general context but lacks direct 'use this when' 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, covering the safety profile. The description adds only the word 'current,' implying dynamic runtime state, but provides no further behavioral detail such as output format or potential latency.

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 with no wasted words. It states exactly what the tool does without redundancy or padding.

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?

This is a simple read-only version tool with no parameters and no output schema. The description, combined with the annotations, fully specifies the tool's behavior and intended use. Nothing essential is missing.

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 input schema has zero parameters and 100% schema description coverage (vacuously). With no parameters to explain, the description does not need to add meaning beyond the schema; the baseline for zero parameters is 4.

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 identifies the resource: 'current MCP platform and adapter versions.' This clearly distinguishes it from sibling tools like authenticate or marketplace, as its sole purpose is version reporting.

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 context is clear: this tool is for retrieving version information. It implies usage when version details are needed, but it does not explicitly mention exclusions or alternatives. For a trivial zero-parameter read tool, this is sufficient.

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 and destructiveHint=false, covering the safety profile. The description adds no extra behavioral details beyond the return content, which is appropriate for a simple read-only tool. It 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?

The description is a single sentence with no filler, front-loading the main action and then listing specifics. Every word contributes to understanding.

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 simplicity of the tool (no parameters, no output schema, read-only), the description fully conveys what the tool returns. It lists all categories of information the agent would need, so it is 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 no parameters in the schema, so the description has nothing to add. Per the rubric, 0 parameters gives a baseline of 4, and the description is not required to explain anything.

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 specific components (installed MCPs, connection status, accounts, catalog tool counts), which distinguishes it from sibling tools like show_version (version) and authenticate. The verb 'Returns' is specific and the resource 'toolkit state' is 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 provides clear context for when to use it: to get an overview of the toolkit's state. However, it does not explicitly mention alternatives or when not to use it, though its purpose is distinct from siblings. This earns a 4.

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 the annotations (readOnlyHint, destructiveHint), the description discloses additional behavioral traits: it is hosted by the platform, requires no platform credentials, is paid via prepaid credit, and clarifies data handling (non-confidential, LGPD compliance). This provides useful transparency 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 contains redundant phrases (e.g., repeating 'consulta' and 'fontes oficiais') and extraneous LGPD context. It is not overly long but could be more concise and structured to convey essential points directly.

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 general context (official source, payment, data privacy) but lacks specifics about return values, error handling, or input constraints. For a simple consultation tool, it is fairly complete, but gaps remain regarding what the output looks like and how to handle failures.

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 lists only 'cpf' and 'cnpj' with no descriptions. The description does not explain their roles, optionality, or relationship (e.g., whether one or both are required). It does not compensate for the lack of schema coverage, leaving parameter meaning ambiguous.

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: consulting negative certificates from STJ via official sources. It specifies the action (consulta) and the resource (certidão negativa do STJ), making the purpose unambiguous and distinct from sibling tools like authenticate or 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?

While the description mentions operational details (official source, payment, no credentials), it does not explicitly state when to use this tool versus alternatives. It lacks guidance such as 'use this when you need to verify a negative certificate' or contrasts with other tools for similar tasks.

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