DJEN (Diário de Justiça)

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

Annotations already indicate idempotent, non-destructive, non-read-only behavior. The description adds useful context: no args returns a login link, passing a token establishes a session, and configuring a header gives a permanent connection. It does not fully describe response details or side effects, but the added behavioral context is meaningful.

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 core purpose, followed by actionable usage details. It is slightly dense with multiple clauses, but every sentence adds useful information and there is no 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?

For a simple, one-optional-parameter authentication tool with no output schema, the description covers the main flows, the recommended configuration, and session-only login. It could mention what the tool returns or error scenarios, but overall it is sufficiently complete for an agent to invoke it 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 input schema only defines 'token' as a string with no description. The tool description fully explains the token's meaning (JWT pasted by the user) and the behavior when omitted (returns the login link), compensating entirely for the 0% schema coverage.

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 MCP.AI for IDE agents via browser login and access token. It distinguishes itself from siblings by specifying the exact auth flow and the two invocation modes (with or without token).

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?

It explicitly explains when to use the token-paste session-only mode versus the recommended permanent config-header approach. It does not explicitly compare against sibling tools like 'connect', but it provides clear usage context and 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description builds on this by adding concrete output behavior: when all providers are connected it returns authenticated:true with empty pending[], and when credentials are missing it returns connect_url and per-install URLs. This provides useful behavioral detail 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?

The description is concise and information-dense. It opens with the core purpose, then immediately covers the two relevant result states. Every sentence earns its place and there is no extraneous content.

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 that the tool has no parameters, no output schema, and simple read-only annotations, the description equips an agent to both select and interpret the tool correctly. It explains the main output fields and the conditional URL behavior, which is complete for the tool's stated scope.

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 no schema coverage burden to compensate for. The description correctly focuses on return behavior instead of parameters, which is entirely appropriate for a no-input status tool.

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 returns connection status and URLs, establishing a specific verb plus resource. It also distinguishes this from sibling tools like authenticate by framing it as a status check rather than an authentication action. The conditional output description adds clarity about what the tool reports.

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 context: it explains what happens when providers are connected and what happens when credentials are missing. It does not explicitly name alternatives like authenticate or state when not to use this tool, but the context is strong enough to infer its primary 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 mark the operation as read-only and idempotent. The description adds useful behavioral context beyond the annotations: the tool returns a URL to a PDF, not the PDF itself, and the input hash comes from the search response. 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?

A single, well-structured sentence that is front-loaded with the main purpose and includes the necessary parameter relationship. No filler or redundant content.

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 one-parameter lookup tool with strong annotations, the description is complete enough: it states what is returned, the required input, and where the input comes from. No output schema is needed to understand the basic behavior.

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%, but the description compensates by explaining that 'hash' is the field 'retornado na busca'. This gives the parameter practical meaning and provenance, even though it does not describe the hash format or length.

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: 'Retorna a URL da certidão (PDF) de uma comunicação do DJEN' and specifies the input dimension ('pelo seu hash'). It also distinguishes itself from the sibling search tool by retrieving a certificate URL for an already-known hash.

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 explains the intended workflow: use the hash returned in the search results from the DJEN search tool. It gives clear context for when to call this tool, though it does not explicitly mention when not to use it or name 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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds practical behavioral details: free, no captcha, and coverage limited to processes published in the Diário. No contradictions found.

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, front-loaded with the core function, and includes limitations and alternatives in a few sentences. No redundant content, though it uses ALL-CAPS emphasis that might be slightly distracting.

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 6 parameters and no output schema, the description covers the main purpose and one major limitation but omits date range handling, pagination details, and tribunal filtering. It mentions the return includes parties and court but not the full structure. Given its complexity, this is a noticeable 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?

Schema description coverage is 0%, so the description must compensate. It only explains nome_parte via 'por NOME de parte' and implicitly the output fields. Parameters like data_inicio, data_fim, sigla_tribunal, pagina, and itens_por_pagina are not described at all, leaving ambiguity in their usage.

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 performs a party-name search on DJEN, grouping by process number and returning process lists with parties and court. It distinguishes from siblings by explicitly noting coverage limits and directing alternate tools for CPF/CNPJ or dormant cases.

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 explicit when-not-to-use: for CPF/CNPJ input or dormant processes, use processos_* tools. Also advises enriching with datajud. This gives clear usage context and 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 declare the tool as read-only, non-destructive, and idempotent, so the description does not need to repeat safety. The description adds that each item brings the full text of the communication, which is a useful behavioral detail. It does not mention other behaviors like pagination, rate limits, or authentication, but the annotation coverage lowers the bar. No contradiction exists.

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, with the main function stated in the first and a clarifying note in the second. It is front-loaded, efficient, and contains no fluff.

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 12 optional parameters, no output schema, and a rich domain, the description is incomplete. It explains the primary search criteria but omits details on pagination, iteration behavior, how filters combine, semantics of 'meio' or 'texto', and any default values. This leaves significant gaps for an agent to safely use 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 schema has 12 parameters with 0% description coverage, placing the burden entirely on the tool description. The description mentions OAB, lawyer name, process number, court, and date, covering several parameters (numero_oab, uf_oab, nome_advogado, numero_processo, sigla_tribunal, data_inicio, data_fim). However, it fails to explain 'meio', 'texto', 'pagina', 'itens_por_pagina', and 'nome_parte', leaving over a third of parameters undocumented. An agent cannot reliably infer their purpose.

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 searches publications/summonses in the National Electronic Justice Diary (DJEN) by specific criteria (OAB, lawyer name, process number, court, date) and returns full text. It also distinguishes itself from jurisprudence databases, which differentiates it from sibling tools like djen_processos_por_parte.

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 a clear context: it is for searching the Official Gazette, not a case law base. This implicitly tells the agent when to use it (for publications/summonses) and when not to (for jurisprudence). However, it does not explicitly name alternative sibling tools, leaving some room for ambiguity.

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?

Adds substantial context beyond annotations: invoke runs tools one-off 'without adding the MCP to the toolkit and without bloating the tool list'; the connect-link and checkout/top-up-link flows with a 'then you retry' instruction; and that 'writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin.' Annotations only declare readOnlyHint=false, openWorldHint=true — the description carries the real behavioral burden and does so thoroughly. No contradiction with annotations (readOnlyHint=false aligns with the documented write actions).

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?

Every sentence carries real information — there is zero padding — but the entire description is one massive unstructured paragraph covering 14 actions plus a second subsystem (prompt library). Despite being front-loaded with the core search→describe→invoke flow, the run-on structure hurts scannability for such a high-surface-area tool. Bullets or section breaks would materially improve readability without adding length.

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 of this complexity (14 sub-actions, 23 params, no output schema), the description is remarkably complete: it covers the end-to-end flow, install-vs-invoke semantics, permission requirements, auth/checkout return behavior, installed-state flags, and the entire prompt-library subsystem. Returns are partly specified (describe returns id+params+pricing+auth; invoke returns connect/checkout links). Minor gaps remain — an explicit description of list_tools' return shape and documentation of the many omitted parameters — but the coverage is strong given the enormous scope.

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, and it partially does: it explains the action enum's dispatch logic, tool_id/mcp_id selection, query intent, and the prompt_vars/prompt_body flow. However, of 23 parameters it leaves limit, immediate, tier_slug, conversation, request_name, cancel_reason, cancel_comment, prompt_targets, report_context, and several others undocumented in both schema and description. The core flow is explained, but the long tail of parameters remains opaque despite a 0% coverage baseline that demands more 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 states the verb+resource with exceptional specificity: 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It enumerates every sub-action with its concrete purpose (search discovers MCPs, describe returns a full profile, invoke RUNS a tool), and clearly distinguishes this composite tool from all siblings by positioning it as the marketplace hub. The prompt-library subsystem is also explicitly scoped ('about ready-made prompt TEXT rather than 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?

Internal action-selection guidance is explicit and excellent: 'Use install only to make an MCP PERMANENT in the active toolkit... prefer invoke for a single/occasional use' and 'list_tools lists what is callable right now.' It also clarifies the retry pattern after connect/checkout links. The only gap is that it never explicitly contrasts itself with sibling tools (e.g., authenticate/connect), instead absorbing those flows via 'invoke returns a connect link,' so external boundary guidance is implied rather than stated.

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 this is a write operation (readOnlyHint false) and non-destructive (destructiveHint false). The description adds context that a conversation array should be included for reproduction, which is useful behavioral detail. However, it does not disclose what happens upon submission (e.g., ticket creation) or clarify the idempotentHint, so it adds only partial transparency.

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 long, front-loads the purpose, and includes only necessary information. There is no redundancy or filler, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (3 params, no output schema), and the description covers the core action and reproduction hint. However, it omits clarification of the message and context parameters, and does not explain expected outcomes (e.g., whether a confirmation is returned). This leaves some gaps for a feedback/reporting 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 coverage is 0% because the description does not systematically describe parameters. It only mentions the conversation array and its purpose (reproduction), while the required 'message' field and 'context' are left undefined. This insufficiently compensates for the lack of schema documentation.

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 reports bugs, missing features, or sends feedback, which distinguishes it from sibling tools like authenticate or djen_get_certidao. It uses a specific verb and resource, though the scope is broad (bug/feature/feedback) rather than hyper-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?

The description implies when to use the tool (when there is a bug, missing feature, or feedback) but does not explicitly mention alternatives or when not to use it. No exclusion criteria are provided, so guidance is only implicit.

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 (readOnlyHint, idempotentHint, destructiveHint) already provide transparency about the tool's non-mutating and idempotent nature. The description aligns with this, and there are no additional side effects or requirements to disclose, so the description fully supports behavioral clarity.

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, concise sentence that conveys the necessary information without redundancy. It is well-structured and front-loaded with the action and target.

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 trivial nature (no parameters, no output schema), the description is complete. It tells the user exactly what information will be retrieved, and there is no missing context that would hinder understanding or usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, so there are no parameter semantics to describe. The description correctly implies this by not mentioning any inputs, and the schema confirms zero 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 clearly states the tool's function: showing current MCP platform and adapter versions. The verb 'show' and the specific resource 'versions' make it unambiguous, and it distinguishes itself 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 implicitly conveys when to use the tool (whenever version info is needed), but it does not explicitly mention alternatives or exclusion criteria. Given the simplicity of the tool and no apparent alternative, this is sufficient, though a brief note on when to call it would be ideal.

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. The description adds useful return details (installed MCPs, connection status, accounts, catalog tool counts) that go beyond the annotations. 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?

One sentence, concise, front-loaded with 'Returns the current toolkit state' and then details. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description fully specifies what the tool returns. For a read-only info tool with no params and no output schema, it's complete. Could mention authentication requirements, but not necessary.

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, schema coverage 100% (trivially). Baseline for zero-para tools is 4. Description adds nothing about parameters since none exist, but that's fine.

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 verb 'Returns' and the specific resource 'toolkit state', enumerating the exact details (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from siblings like authenticate or connect, 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 clearly implies that this tool is for querying overall toolkit state, but it does not explicitly state when to use vs. alternatives. Since it's a read-only info tool, the context is clear, but no exclusions or alternatives are mentioned.

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