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, and the description meaningfully adds behavioral context beyond those: the 2020 publication coverage limit, the fact that count_processos: 0 does not prove absence of a process, and the presence of an ausencia block. This is valuable non-obvious behavior for an 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 dense and front-loaded with the core purpose, then moves to limitations, zero-result semantics, and alternatives. Each sentence adds needed information, though the paragraph is long and could be slightly restructured into clearer segments.

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 6 parameters and no output schema, the description covers the main use case, return shape, coverage limitations, absence semantics, and alternative routing. It could more explicitly describe pagination or date-filter parameters, but it provides enough context for an agent to invoke the tool correctly for the primary flow.

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 needs to compensate. It clarifies the main required parameter, nome_parte, by saying the lookup is by name of the party and by explicitly routing CPF/CNPJ input elsewhere. However, the five optional parameters—pagina, data_fim, data_inicio, sigla_tribunal, and itens_por_pagina—receive no semantic explanation beyond their self-explanatory Portuguese names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'DESCOBERTA por NOME de parte' and states it searches DJEN by party name, groups by process number, and returns a list of processes with parts and court. This clearly distinguishes it from sibling DJEN tools and from the alternative processos_* engine tools mentioned in the text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: it is for name-based discovery, free, and covers only processes published in the Diário from 2020 onward. It also states when NOT to use it: for CPF/CNPJ input or dormant processes, use processos_* tools, and it suggests enriching results with datajud.

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?

Mesmo com annotations de readOnlyHint, idempotentHint e destructiveHint, a descrição adiciona comportamento relevante: cada item traz o texto completo, a cobertura temporal é apenas a partir de 2020 e pode variar por tribunal, e resultados vazios retornam um bloco 'ausencia' com motivos específicos. Não há contradição com as 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 descrição é longa, mas cada frase agrega valor: escopo, conteúdo retornado, limitações de cobertura e comportamento de resultados vazios. As informações críticas estão na frente e a estrutura com parênteses ajuda a organizar as ressalvas sem poluir a leitura.

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?

Para uma ferramenta de 12 parâmetros, sem output schema e sem descrições de parâmetros, a descrição cobre bem o essencial: finalidade, cobertura, conteúdo dos itens e tratamento de ausência de resultados. Faltam detalhes sobre paginação, formatos de data e os parâmetros não mencionados, mas o núcleo operacional está presente.

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?

Com 0% de cobertura descritiva no schema para 12 parâmetros, a descrição deveria compensar mais. Ela cita os filtros principais (OAB, nome de advogado, número de processo, tribunal e data), mas não explica parâmetros como 'meio', 'texto', 'pagina', 'nome_parte' ou 'itens_por_pagina', deixando lacunas para o agente.

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?

A descrição abre com verbo específico 'Busca publicações/intimações no DJEN por OAB, nome de advogado, número de processo, tribunal e data', definindo claramente o recurso e o escopo. Também diferencia a ferramenta de bases de jurisprudência/ementas e de cadastro de processos, deixando claro o que ela não é.

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?

A descrição orienta explicitamente quando o resultado vazio NÃO significa que o processo não existe, e recomenda confirmar em datajud_get_processo, que é o índice histórico. Também estabelece limites de uso ao afirmar que não cobre jurisprudência/ementas nem cadastro de processos, ajudando o agente a escolher a ferramenta correta.

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.