Conselho Nacional de Justiça: Serventias Extrajudiciais (Lista)

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

Annotations indicate idempotentHint=true (safe to repeat) and destructiveHint=false. The description adds that the token is a JWT and that config-based connection is permanent and non-expiring, which is useful. However, it does not mention any side effects (like creating a session) or the exact behavior of returning a link (e.g., does it open a browser? It implies redirecting user to browser). The description provides moderate context beyond 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 but it is dense and front-loaded with 'MCP.AI for IDE agents'. It includes practical instructions, but the fl ow is a bit convoluted: it alternates between config and session options, which may confuse. It is reasonably concise but could be better structured with clear steps.

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 1 optional parameter, no output schema, and annotations that are minimal (no readOnly, but idempotent), the description provides enough for basic use but lacks details on return value (e.g., what is returned on success) and error handling. It covers the main use cases but not edge cases. Overall, adequate but not comprehensive.

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 coverage is 0% (schema has no descriptions), so the description carries the burden. It explains that 'token' is a JWT pasted by the user and that it can be omitted to get a link. However, it does not specify token format requirements, validity, or error cases. This is minimal compensation for a single parameter.

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 is for authentication, providing a login link or accepting a token. It distinguishes from siblings by focusing on auth, but it does not explicitly name alternatives, leaving some ambiguity about when to use 'connect' instead.

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 usage scenarios: add token to config for permanent connection, or paste token for session-only login, or call with no args to get link. It also mentions the target audience (IDE agents). However, it does not explicitly state when NOT to use this tool or mention alternatives like 'connect'.

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 read-only and idempotent annotations, the description discloses that the tool consumes prepaid credits, originates from official sources, is not confidential, and imposes LGPD compliance responsibilities. These behavioral details are not covered by annotations and are valuable for the agent.

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, somewhat redundant paragraph (repeats 'official source' twice) and includes legal boilerplate about LGPD. It could be more concise, but it is not excessively long and follows a logical flow from source to usage conditions.

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 list-query tool, the description sufficiently covers the data source, access conditions, and legal considerations. It does not specify output format, but given the simplicity and lack of output schema, the provided context is adequate for decision-making.

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 includes 'uf' and 'municipio' as required strings, but the description does not explain their meaning, allowed values, or how they affect the query. The agent is left to infer that 'uf' is a Brazilian state and 'municipio' is a municipality, which is not explicit.

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 queries a list of extrajudicial services from the official CNJ source. It specifies the nature of the data (official, non-confidential) and differentiates from sibling tools like authentication or connection tools by focusing on a specific data query.

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 some usage context (requires prepaid credits, no platform credentials needed, official data), but it does not explicitly state when to use this tool versus alternatives or provide conditional usage guidance. It implies a query scenario but lacks direct comparison to sibling tools.

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 idempotent behavior. The description adds valuable context by specifying exact return values for different states (authenticated:true vs connect_url), which goes beyond the structured 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 sentences, front-loaded with the primary purpose, and every sentence adds meaningful detail about conditional behavior. 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?

For a zero-parameter, read-only tool with no output schema, the description fully covers its behavior in both relevant states. It is complete 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 baseline is 4. The description doesn't need to explain parameter semantics and adds no irrelevant information.

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 'Returns' and clearly states the resource: connection status and URLs. It also distinguishes the tool by describing two conditional states (connected vs missing credentials), which differentiates it from siblings like authenticate.

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 on when to use the tool: to check connection status and get URLs. It doesn't explicitly name alternatives or exclusions, but the behavior is clear enough to infer appropriate use.

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 like readOnlyHint=false and openWorldHint=true, the description adds essential context: invoke works even when the MCP isn't installed, runs one-off without bloating the tool list, and handles auth/payment edge cases via connect/checkout links. It also clarifies permission requirements for write actions, going well beyond what annotations convey.

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 (~400 words) but well-organized, front-loading the core flow and key differentiators. It uses paragraphs and bold/uppercase for emphasis, making it readable despite its length. Every section adds value, though it could be tightened with bullet points for the many sub-actions.

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 (23 params, no output schema, zero schema coverage), the description is remarkably complete. It covers the full lifecycle, including discovery, execution, permissions, auth/payment fallbacks, permanent vs. one-off usage, and the prompt library sub-features. This is sufficient for an agent to use the tool effectively.

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 the 23 parameters. It explains the core parameters like action, mcp_id, tool_id, and arguments, and mentions prompt-related fields indirectly, but does not cover all parameters (e.g., cancel_reason, prompt_targets, tier_slug). The high-level flow provides some meaning, but not exhaustive parameter 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 that this is the mcp.ai marketplace tool, encompassing discovery, description, and execution of MCPs, plus a prompt library. It details the core flow (search → describe → invoke) and explicitly mentions sub-features like install, subscribe, and prompt publishing, making its purpose unambiguous and differentiating it 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?

The description provides explicit usage guidance: it outlines the core flow, advises 'prefer invoke for a single/occasional use' and 'use install only to make an MCP PERMANENT', explains when invoke returns connect/checkout links and how to retry, and notes that write actions require workspace owner/admin. This thoroughly addresses when to use this tool 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?

Annotations already provide idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds the behavioral detail that the conversation array is needed for reproduction, which is useful context. However, it does not go beyond this, such as explaining response behavior or side effects. With annotations covering the baseline, a 3 is appropriate.

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 with no unnecessary words. The main purpose is front-loaded, and the reproduction instruction is clearly separated. 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 the tool's simplicity (3 parameters, no output schema, no nested objects), the description is mostly complete. It covers the core function and the key parameter. It could optionally mention the response or clarify 'context', but the description is sufficient for a basic bug-reporting tool. A minor gap prevents a 5.

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. It explains 'conversation' by calling it an array of recent messages, but the schema types it as a string, creating potential confusion. It does not clarify 'message' or 'context', leaving those parameters underspecified. The compensation is only partial, so a 2 reflects the 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 uses a strong imperative verb 'Report' and clearly specifies the resource: bug, missing feature, or feedback. This clearly distinguishes it from sibling tools like authenticate or marketplace. It is not a tautology and leaves no doubt about 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 implicitly tells when to use the tool (when encountering a bug or wanting to provide feedback) and even adds the instruction to include the conversation array for reproduction. It does not explicitly mention alternatives, but given the distinct purpose among siblings, this is acceptable. Lacks explicit 'when not to use' but the 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful context by specifying it reports 'MCP platform and adapter versions,' which clarifies return content 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?

A single, grammatically simple sentence that is front-loaded and contains zero filler. Every word 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?

For a zero-parameter, read-only tool with strong annotations, the description fully conveys purpose and output. Even without an output schema, it specifies the key content (platform and adapter versions), making it complete for agent 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 tool has zero parameters, so the baseline is 4; the input schema is empty and fully 'covered' by the description. No parameter documentation is required or missing.

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 uses specific verb 'Show' and identifies the exact resource 'current MCP platform and adapter versions,' making the function immediately clear. It naturally distinguishes from sibling tools like authenticate, connect, and toolkit_info, which 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?

The tool's purpose is self-evident for retrieving version information, and no sibling tool offers a comparable function. While explicit when-to-use guidance is absent, the context is clear and there are no exclusions; a minor deduction only for not stating 'use when you need version info' directly.

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 idempotentHint=true, and the description adds meaningful context about the returned state (MCPs, status, accounts, catalog tool counts). It doesn't mention potential edge cases like empty states, but it doesn't contradict the annotations. This adds value 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, well-structured sentence that front-loads the core purpose ('Returns the current toolkit state:') followed by a colon-led list of specific attributes (MCPs, status, accounts, catalog tool counts). Every word earns its place with no unnecessary padding 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?

Given the tool's simplicity (zero parameters, no output schema, read-only), the description fully captures what the agent needs to know. It enumerates all the elements of the toolkit state that will be returned, leaving no ambiguity about the tool's behavior. The annotations cover safety, and the description covers content.

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 there is nothing for the description to add. The rubric specifies a baseline of 4 for zero-parameter tools, and the schema coverage is at 100% trivially. The description correctly focuses on the return value rather than 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 uses a specific verb and resource: 'Returns the current toolkit state', then details exactly what that includes: 'installed MCPs, their connection status, the accounts connected to each one, and how many catalog tools each exposes.' This clearly differentiates it from siblings like show_version and marketplace by referencing MCPs and connections.

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 this tool but does not explicitly mention when not to use it or reference alternatives. For example, it doesn't contrast with siblings like marketplace or show_version, so an agent must infer that this is the go-to for connection-state information. The usage context is clear but not made explicit.

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