DataJud (CNJ)

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

Annotations declare idempotentHint=true, which aligns with the description's suggestion to retry. The description adds valuable behavioral context: the tool either returns a link or accepts a token; it explains the side-effect of permanent authentication via config modification. No contradictions 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 two sentences, front-loaded with the tool's role, then immediately provides actionable usage options. Every sentence is essential, no redundancy or wordiness.

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 low complexity (1 optional param, no output schema) and rich annotations, the description covers all necessary aspects: authentication flow, two modes, permanent vs session, and config integration. No gaps remain.

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 for the only parameter 'token'. The description fully compensates by explaining its purpose: 'paste <jwt>' for session login, or omit to get a link. This adds complete meaning beyond the schema's bare type string.

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 users for MCP.AI in IDE agents. It specifies the two authentication methods (permanent via config header, session via token) and distinguishes itself from sibling tools like 'connect' and 'marketplace' by being the sole authentication 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 explicitly tells when to use the tool: to get a login link (call with no args) or to complete login by pasting a token (call with token). It also contrasts the permanent (config header) vs session (paste token) approaches, providing clear guidance. Lacks explicit 'when not to use' scenarios, but context makes it 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?

Annotations provide readOnlyHint, idempotentHint, destructiveHint; the description adds behavioral details beyond these, such as the specific return values for connected vs. missing credentials states. This adds value 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 sentences, highly concise, and front-loaded with the core purpose. Every sentence provides essential information without waste.

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 no output schema, the description adequately explains return values (authenticated, pending, connect_url) and their meanings in different states. No additional details are needed for this simple 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?

There are no parameters, so schema coverage is 100%. The baseline for 0 parameters is 4, and the description adds no parameter information, which 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 returns connection status and URLs, distinguishing between 'all providers connected' and 'credentials missing' states. It differentiates from sibling tools like 'authenticate' by focusing on status rather than initiation.

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 (to check connection status) by describing the output states. It does not explicitly mention when not to use it or name alternatives, 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 indicate read-only, idempotent, non-destructive behavior. The description adds context that the input CNJ number can have formatting ('com ou sem máscara') and lists return types (metadata + movements). No contradictions.

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, each providing essential information. The description is front-loaded with the main action and returns. 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 tool with 2 parameters, enum on one, and no output schema, the description is complete enough: specifies input and output. Could mention if there are limitations (e.g., not all courts support mask removal) but not required.

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%, so description must compensate. It explains 'numero_processo' is the CNJ number and can be with or without mask, and 'tribunal' is the court (enum is clear from schema). Adds some value but does not fully detail parameter constraints or format.

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: to search for a process by its unique CNJ number (with or without formatting) in a specific court, returning metadata and movements for each instance found. This distinguishes it from siblings like datajud_search (broader) and datajud_movimentos (movements only).

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 have a CNJ number and court, but does not explicitly state when to use this tool versus alternatives like datajud_search or datajud_movimentos. No exclusions or prerequisites are provided.

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, destructiveHint=false, so the description's safety claims are redundant. The description adds that it returns a timeline with metadata, but lacks details on pagination, limits, or error behavior. No contradictions.

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 that efficiently conveys the tool's purpose and ideal use case, with no unnecessary 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 tool with 2 required parameters, no output schema, and simple purpose, the description is minimally adequate. It conveys the core function and use case, but lacks parameter explanations and output details, which are needed for full completeness.

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%, and the description does not explain the parameters. While 'tribunal' is self-explanatory via its enum, 'numero_processo' is not defined, leaving ambiguity about expected format. The description only mentions 'de um processo' but fails to clarify 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 it returns only the timeline of movements with metadata for a process, and explicitly distinguishes itself as ideal for detecting new movements, differentiating it from sibling tools like datajud_get_processo.

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 includes 'ideal pra detectar se houve movimentação nova,' indicating when to use it, but does not explicitly exclude other scenarios or mention alternatives. The context of sibling tools provides implicit 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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds that it sends a raw query (consistent with read-only) and that pagination beyond 10k requires search_after. Also mentions response includes raw_data. Adds meaningful behavioral context beyond annotations, such as the pagination constraint.

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?

Three short sentences, each providing essential information: purpose, pagination guidance, response content. No fluff, front-loaded with the most critical info. 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 moderate complexity (6 params, no output schema) and 0% schema coverage, the description covers purpose, key parameter usage (tribunal, query, search_after), and response includes raw_data. However, it omits details on 'from', 'size', 'sort', and any error handling or response structure beyond 'raw_data'. Adequate but has gaps.

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 description must compensate. It clarifies that 'query' is a raw Elasticsearch query body, 'tribunal' is a court from a specific list, and 'search_after' is for pagination. However, it does not explain 'from', 'size', or 'sort' parameters, which are present in the schema. Adds value for some parameters but incomplete.

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 clearly states the tool sends a raw Elasticsearch query body to a court index (tribunal). It calls itself an 'escape hatch' and specifies that it's advanced, distinguishing it from standard tools like datajud_search. The verb 'envia' and resource 'query Elasticsearch cru pro índice do tribunal' are specific.

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?

Provides guidance on using search_after for pagination beyond 10k results. Calls the tool an 'escape hatch,' implying it's for advanced cases. However, it does not explicitly state when to prefer this over alternatives like datajud_search, nor does it list exclusions. Clear context but lacking explicit when-not-to-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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral details: pagination, ordering by filing date, and the non-indexing of party names/OAB. This provides useful context beyond the annotations, such as the scope and limitations of the data.

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: first sentence covers purpose, filters, pagination, and ordering; second sentence covers limitations and alternatives. Every sentence is necessary and efficient, with no fluff. Front-loaded with the core purpose.

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 search tool with 8 parameters, no output schema, and read-only annotations, the description provides a solid overview. It explains the main use case, key filters, pagination, and what is not indexed. It lacks details on sort direction and parameter ranges, but overall it is sufficiently complete for an agent to understand when and how to invoke 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?

Schema description coverage is 0%, so the description must compensate. It mentions search parameters like tribunal, classe_codigo, orgao_julgador_codigo, assunto_codigo, and pagination (from/size). However, it does not describe sort_desc or numero_processo, leaving some parameters unexplained. It adds value for the main filter parameters but is not comprehensive.

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 it searches processes in a tribunal by class, judging body, and subject codes, with pagination and ordering by filing date. It also distinguishes itself by explicitly stating what it does not do (index party name/OAB) and points to an alternative tool (djen/escavador). This is specific and complete.

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 states when to use this tool (for tribunal search by court codes) and when not to (for party name or OAB search). It provides a direct alternative ('use o MCP djen/escavador'), giving clear guidance on tool selection.

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=false, openWorldHint=true, etc. Description adds important context: 'Writes require workspace owner/admin' and explains flat-mode behavior for list_tools/invoke. No 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?

Description is well-structured, starting with purpose then detailing actions. Some redundancy but overall efficient for the 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?

Adequate for a multi-action tool with many parameters, but lacks parameter descriptions and does not explain return values (no output schema). Moderately 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?

Schema coverage is 0%. Description only explains the 'action' parameter's enum values and gives high-level context for some parameters, but does not describe 13 parameters like limit, query, mcp_id, etc. Insufficient 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?

Description clearly states 'THE official mcp.ai marketplace' and lists all possible actions (search, describe, install, etc.), distinguishing it from external registries and 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?

Explicitly instructs to use this tool FIRST for discovering MCPs before external registries, and provides context for each action (search first, describe for details, install/uninstall for management, etc.).

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 idempotentHint true and destructiveHint false. Description adds value by instructing to include conversation for reproduction, but doesn't disclose side effects or post-submission 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?

Two sentences with no waste; front-loaded purpose and key usage instruction.

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 no output schema, description should cover return value or confirmation. It only covers input, leaving agent without post-call expectations.

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 coverage, description partially explains 'message' and 'conversation' parameters, but omits 'context'. It adds some meaning but is incomplete.

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 clearly states the tool reports bugs, missing features, or sends feedback, using specific verbs. It distinguishes well from unrelated sibling tools like authenticate or datajud_*.

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?

Description implies usage for bug reports and feedback, but does not explicitly mention when not to use or suggest alternative tools. Context is clear but lacks 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 indicate read-only and idempotent behavior; description adds context about version specifics but does not go beyond.

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?

Single sentence, 9 words, no redundancy; front-loaded and efficient.

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 simplicity and annotation coverage, description is sufficient for the tool's purpose; no missing needed 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?

No parameters, so description doesn't need parameter details; baseline 4 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?

Description clearly states the tool shows MCP platform and adapter versions, with a specific verb and resource that distinguishes it from siblings.

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?

Description implies usage for checking versions but does not explicitly state when to use or exclude alternatives; no siblings with similar purpose.

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, destructiveHint, idempotentHint. Description adds value by detailing what state is returned (MCPs, status, catalog counts). No additional behavioral traits needed.

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?

Single sentence, no redundancy, front-loaded with key action and output.

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 annotations covering safety, the description fully explains the output and purpose.

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?

No parameters in schema, baseline is 4. Description does not need to add param meaning.

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 clearly states it returns current toolkit state including MCPs, connection status, and catalog tool counts. Specific verb+resource, 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?

Clear context as a read-only status tool, but no explicit exclusions or alternative tools mentioned. Context is sufficient for simple use.

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