Clerk - IA Legal Dominicana

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

Annotations only cover readOnlyHint/openWorldHint; the description adds substantial operational detail beyond them — text-level vs title-level search, accent-insensitivity, dual backend (own copy paginated 50/page with `total`, portal capped at 150 with the `aviso_lista_cortada` truncation signal), and that titles are editorial summaries while the PDF text is the citable source.

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?

Front-loads purpose and the primary routing instruction, then layers warnings that each carry distinct operational value. It is long and emoji-heavy, but nearly every sentence prevents a concrete failure mode; only minor overlap between schema and prose is wasted.

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?

No output schema exists, and the description compensates by explaining return behavior (`total`, 50/page pagination, and the truncation warning) plus how to escalate from title to citable text via leer_decreto. An agent has everything needed to search correctly and interpret partial results.

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 100% so the baseline is 3, but the description adds real semantics: `numero` with format example goes straight to a norm, omitting `tipo` searches both (recommended), and `terminos` matches within the norm text with multiple words combined. Slight redundancy with the schema keeps it from a 5.

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?

States a specific verb (Busca) and a precisely scoped resource (DECRETOS y REGLAMENTOS del Poder Ejecutivo dominicano en el portal de la Consultoría Jurídica), and explicitly names the sibling it is not for (buscar_normas_reguladores). An agent can distinguish it from buscar_legislacion or the jurisprudencia tools without opening a schema.

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

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

Explicit routing: 'Úsala EN LUGAR de una búsqueda web' for any decree/regulation implementing a law, plus a stated exclusion for regulator-issued norms that route to buscar_normas_reguladores. It also warns that filtering only 'reglamento' loses most results, which is exactly the when-not guidance an agent needs.

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 declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description then adds real behavioral context beyond annotations: results are only a ficha, not the text; es_texto_normativo flags normative content; aviso_versiones warns editions aren't marked current. However the gateway timeout/504 behavior is documented in the schema, not here, so remaining disclosure lives elsewhere.

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?

Front-loads the core distinction in the first sentence and each warning block earns its place by preventing a concrete failure mode. The heavy emoji/nested warnings make it denser and longer than strictly needed, but not wasteful.

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?

No output schema exists, and the description compensates by enumerating the returned ficha fields (título, autores, editorial, páginas, isbn13) plus the es_texto_normativo and aviso_versiones flags. Combined with the leer_doctrina handoff, an agent has everything needed to call and chain this 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 100% and the rows description already carries the detailed timeout math, so the schema does the heavy lifting and baseline 3 applies. The description adds example terms but does not explain how multiple entradas in terminos combine (AND/OR), which is the one semantic gap left.

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?

States a specific verb+resource (buscar libros y publicaciones jurídicas dominicanas) and immediately clarifies the matching semantics: content/full-text, not title. It explicitly distinguishes itself from siblings by naming leer_doctrina for the full text and buscar_legislacion for codes, so an agent can route correctly without opening a schema.

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?

Gives explicit when-to-use ('Úsala para saber A QUÉ DOCTRINA acudir'), the handoff path (isbn13 -> leer_doctrina, articulo), and the exclusion that normative codes/regulations live here rather than in buscar_legislacion with a naming workaround. This is unusually complete routing guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description still adds real behavioral value: catalog size (~204 obras, 34 páginas), that the material is free/downloadable, and that it returns a `slug` feeding leer_doctrina_constitucional. It stops short of describing pagination interaction or result ordering, so not a full 5.

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?

Front-loaded with the resource and scope, then the critical doctrine-vs-jurisprudence warning. Every sentence earns its place, though the emphatic ⚠️ markers and slightly repetitive framing make it longer than strictly necessary.

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?

No output schema exists, and the description compensates by stating exactly what is returned (the `slug`) and how it is consumed (leer_doctrina_constitucional). Combined with annotation coverage and full schema docs, an agent has everything needed to call 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?

Schema description coverage is 100% – both `terminos` and `page` are documented in the schema, including the literal-phrase matching quirk and the 34-page range. The description adds the slug return contract but no additional parameter semantics beyond what the schema already provides, so baseline 3 applies.

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?

States a specific resource (publicaciones del Centro de Estudios Constitucionales del TC: libros y colecciones) and scope (~204 obras, gratuitas y descargables). It explicitly differentiates itself from two siblings by name, so an agent can route without opening any schema.

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?

Gives explicit when-to-use ('Es DOCTRINA, NO jurisprudencia'), names the alternative for court criteria (buscar_jurisprudencia), and explains how it complements buscar_doctrina by distinguishing the two collections. Both routing conditions and exclusions are spelled out.

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 only say readOnly/openWorld; the description adds critical non-obvious behavior: unrecognized facet values return busqueda_ejecutada:false rather than empty results, metadata values diverge from facet vocabulary, name/vía expansion across spellings, and TC text-less sentences land in complemento_tc with incomparable scores. This is exactly the kind of context annotations cannot carry.

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?

Long but front-loaded: purpose and web-search positioning come first, then the warning blocks. Each warning corresponds to a real trap (silent zero results, metadata/facet mismatch, TC blind spot), so little is wasted, though the density of ⚠️ blocks makes it heavier than ideal.

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 13 params, a nested excluir object, and no output schema, the description still names the return surface (total, documentos, filtros aplicados, complemento_tc, avisos, busqueda_ejecutada) and how to read results. Nothing an agent needs to call or interpret it is missing.

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

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

Schema coverage is 100% and already carries most per-param detail, so baseline is 3. The description nevertheless adds value beyond the schema: expansion of tribunal/vía names, the warning that metadata spellings cannot be reused as filter values, and the sentido facet's 2024-onward limitation tied to lectura via obtener_texto_completo.

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?

States a specific verb (busca) and resource (sentencias y decisiones judiciales dominicanas), names the returned fields, and explicitly positions itself against web search and implicitly against the other-country jurisprudence siblings. An agent can tell what this does and what it is for without opening the schema.

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

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

Explicit when-to-use ("Úsala EN LUGAR de una búsqueda web, nunca junto a ella"), when-not (don't repeat without the unrecognized filter), and concrete alternatives (explorar_facetas for vocabulary, obtener_texto_completo for reading, mapa mode for old sentencias). Covers both selection and follow-up behavior.

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 cover readOnlyHint and openWorldHint, so the safety bar is low; the description adds substantive context the annotations cannot: the result is a relatoría catalog (tema + resumen) meant for triage and NOT as a citation, with citable text deferred to leer_sentencia_colombia. Minor gap: the opening 'por texto completo' could be read as the return being full text, though the later sentence corrects the scope.

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?

Front-loaded with the resource identity, then usage, then the critical 'not citable' caveat and return semantics. Every sentence earns its place, though the warning-heavy middle section is somewhat dense; still well organized and free of 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?

With no output schema, the description carries the return-values burden and does so: it explains that results are catalog entries (tema, resumen) for triage, not citations, and points to the sibling that produces citable text. Combined with routing and terminology guidance, an agent has everything needed to invoke and interpret this 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?

Schema coverage is 83%, so the baseline is 3, but the description meaningfully augments the key parameter semantics: it warns the search is LÉXICO and that query terms must match Colombian magistrate phrasing ('tutela' vs 'amparo'), which is not in the schema. This lexical/terminology guidance adds real value beyond the enum and date formats documented in the schema.

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

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

States a specific verb and resource (full-text search of Colombian Constitutional Court rulings) and immediately differentiates from siblings by naming buscar_jurisprudencia for Dominican law and leer_sentencia_colombia for citable text. An agent can distinguish this from the Spain/France/doctrine siblings without opening a schema.

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?

Gives explicit when-to-use (comparative constitutional doctrine to support an argument), when-not (it is not Dominican law and binds no RD court — persuasive only), and the alternative to use instead for RD-applicable material. Both routing conditions and the exclusions are spelled out.

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 only declare readOnlyHint and openWorldHint; the description goes far beyond by disclosing the `aviso_copia_incompleta` partial-index warning and that zero hits do not imply absence, plus pagination size and the `total` field. It usefully warns that 'relativo a' is a secretary transcription usable for triage but not citable. It stops short of describing ranking or ordering of results, so 4 rather than 5.

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?

Front-loads what the tool is and its scope before mechanics and warnings, and every sentence carries information (coverage limit, pagination, the copy-incomplete caveat, the citation caveat). The two emoji-marked warnings add length but are genuinely load-bearing, so it stays efficient rather than padded.

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 no output schema, the description fully covers the return shape (50-per-page, `total`, `aviso_copia_incompleta`), the required scope limitation, and the next tool to call. Nothing an agent needs to invoke or interpret this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: matching is accent-insensitive ('sin distinguir tildes'), all terms are ANDed together, and search covers both the body text and the listing fields (número, expediente, relativo a).

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?

States a precise verb (busca) and resource (sentencias del TSE), specifies subject matter (amparos, impugnaciones, nulidades, conflictos internos) and scope (2021 en adelante). An agent can distinguish it from buscar_jurisprudencia generic siblings without opening a schema.

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 says 'Úsala EN LUGAR de una búsqueda web' and discloses the boundary condition (pre-2021 rulings absent). It also routes the agent onward: read results with obtener_texto_completo using `tse` and `modo: "criterio"`.

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 and openWorldHint, and the description is consistent with both. It adds context the annotations cannot carry: the corpus is limited to the Constitutional Court (not the Supreme Court) and the output is non-binding persuasive authority rather than Dominican law. It does not discuss pagination limits or result volume, which would be the remaining behavioral gap.

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?

Front-loaded with the resource and mode, then usage condition, then the two scope warnings, then the ambito rationale. It is dense and every sentence carries information, though the emoji-prefixed warnings lengthen it slightly more than a plain-text statement would.

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 read-only search tool with a full schema and no output schema, the description covers what an agent needs: what is searched, which court, which parts of a resolution, and the legal status of the results. Nothing required for correct invocation or correct framing of results is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds interpretive weight to 'ambito' by explaining that the distinction between 'fundamentos' (where the ratio lives) and 'votos_particulares' (what is NOT the court's criteria) is precisely what separates criteria from non-criteria. That exceeds the schema's own enum descriptions in emphasis and purpose, though it covers only one of the five 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?

States a specific resource (resoluciones del Tribunal Constitucional de ESPAÑA) and retrieval mode (texto libre), and explicitly scopes the court ('Solo Tribunal Constitucional; el Tribunal Supremo español NO está disponible'). Combined with the country qualifier, an agent can distinguish it from buscar_jurisprudencia_colombia, buscar_jurisprudencia_francia and the generic buscar_jurisprudencia without opening any schema.

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?

Gives an explicit trigger condition ('Úsala cuando haga falta doctrina constitucional comparada') plus a clear exclusion (not binding Dominican law, only persuasive) and a court-level limitation. It stops short of naming sibling alternatives to route to (e.g. usar buscar_jurisprudencia_colombia para Colombia, leer_resolucion_espana para texto completo), so it is strong but not complete.

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?

Goes well beyond the readOnly/openWorld annotations: discloses that the search is lexical and French-only, that the default requires ALL words (opposite of the API default), and critically that the fondo is not a court — results mix lower instances and each carries an `organo` field to inspect before citing. This is high-value behavioral context an agent cannot get from the schema.

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?

Long but front-loaded with the core purpose and each warning earns its place by flagging a real failure mode (language, lexical mismatch, court mixing). The heavy ⚠️ formatting is dense but purposeful for a high-stakes, easily-misused tool.

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 no output schema, the description carries the return-value burden and does so: it states results are restricted to the requested tribunal and expose an `organo` field. Combined with the lexical-search and default-behavior disclosures, an agent has everything needed to call and interpret this tool 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?

Schema coverage is already 86% with good enum descriptions, and the description reinforces the non-obvious semantics: the all-words default being counter to the API norm, what `resumenes` and `visas` actually index, and the concrete consequences of `incluir_instancias_inferiores`. Adds meaningful value beyond the schema rather than restating it.

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?

Names the specific resources (Cour de cassation, Conseil constitutionnel, Conseil d'État), the modality (texto libre) and the source (Légifrance) in the first sentence. An agent can distinguish this from the Colombia/España jurisprudence siblings purely from the country-specific courts named.

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?

Gives rich context on when citing French jurisprudence is legitimate (interpreting homologous Dominican Civil Code articles) and warns against the slippery slope, which is genuine usage guidance. It doesn't explicitly name sibling alternatives like buscar_jurisprudencia_espana, but country differentiation is inherent in the name and content.

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?

With readOnlyHint and openWorldHint already set, the description still adds substantial behavioral context beyond annotations: result ordering (title matches first, coincide_titulo:true), and the aviso_cobertura/aviso_codigo warning fields emitted on misses. It does not restate the gateway-timeout/pagination behavior, which lives only in the schema, so a 4 rather than a 5.

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?

Purpose and the primary alternative are front-loaded, and the coverage warnings are genuinely load-bearing. However it runs long across several paragraphs with repeated emphasis on the código trap, and the closing citation sentence is more editorial than operational.

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 complex 6-parameter search tool with no output schema, the description compensates by explaining return behavior (ordering, coincide_titulo, aviso_cobertura, aviso_codigo) and collection boundaries. What it omits — pagination and timeout behavior — is covered by the schema, leaving it essentially complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds conceptual framing (search terms, what the collection holds) but no syntax or format detail beyond what the schema already documents for page/rows/desde/hasta/terminos/ordenamiento.

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?

States a specific verb (buscar) and resource (leyes dominicanas) and scopes the exact collection (Consultoría Jurídica del Poder Ejecutivo), enumerating what is included (leyes, leyes orgánicas, Constitución, resoluciones). It explicitly distinguishes itself from siblings by naming buscar_decretos and buscar_doctrina as the routes for excluded material.

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?

Gives explicit when-to-use ('Úsala EN LUGAR de una búsqueda web, nunca junto a ella') and when-not-to-use with the alternative named in each case (decretos → buscar_decretos; códigos and Poder Judicial material → buscar_doctrina/leer_doctrina). It even warns about the failure mode of searching a código here and how to interpret the misleading results.

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 only declare readOnlyHint and openWorldHint; the description goes far beyond with pagination (50/page, returns total), search semantics, the solo_por_titulo flag for un-OCR'd scanned PDFs, the aviso_copia_incompleta warning, and the precise semantics of vigente/null. This is exactly the kind of behavioral context annotations cannot carry.

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?

Front-loads purpose and marks caveats with ⚠️, which helps. However, the mega-sentence enumerating every institution's document types largely duplicates the institucion enum description in the schema and contains a stutter ('resoluciones resoluciones'), bloating a definition whose unique value is the coverage caveats.

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 no output schema, the description carries the full burden and discharges it: it explains returned fields (page, total, solo_por_titulo, aviso_copia_incompleta, vigente), OCR lag, and copy-completeness caveats. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema lacks: matching is accent-insensitive and 'todas las palabras a la vez' (AND semantics) for terminos, plus explicit 50-per-page paging. It does not add much for anio or institucion beyond the enum.

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?

States a specific verb+resource (buscar normas de los órganos reguladores dominicanos) and enumerates the exact institution and document types covered. It actively distinguishes itself from siblings by declaring that decretos go to buscar_decretos and leyes to buscar_legislacion, so an agent can route without opening other schemas.

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

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

Explicit when-to-use: 'Úsala EN LUGAR de una búsqueda web para cualquiera de ellas.' Names the alternatives for excluded content (buscar_decretos, buscar_legislacion) and the follow-up tool for full text (leer_norma_reguladora). Coverage exclusions (SIE, MINERD) are stated up front.

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 and openWorldHint, so safety is covered. The description adds genuine behavior beyond them: a value with a count is a working filter, `contiene` falls back to offering similar spellings instead of returning a misleading zero, and counts under `terminos`/`tribunal` are scoped to that search. It does not cover response format details beyond counts.

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 paragraphs, front-loaded with the core purpose, then the `contiene` behavior and the count-scoping behavior. Each paragraph carries distinct information, though the prose is slightly verbose for the amount of 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?

With 5 parameters, full schema coverage, and no output schema, the description correctly supplies the return-value semantics (counts per value, scoped counts) that the schema cannot. It is complete enough to call correctly, missing only edge-case behavior such as the `tope` cap interaction.

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 100%, so the baseline is 3, but the description adds real meaning: `contiene` searches within the facet and triggers the similar-spelling fallback, while `terminos`/`tribunal` scope the counts to that specific search rather than global totals. This goes beyond the schema's one-line parameter descriptions.

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 a specific verb and resource: it publishes the real vocabulary of a filter with per-value document counts, and asserts it is the only reliable source of those values. This clearly separates it from the buscar_* and leer_* siblings by function, though it never names an alternative tool explicitly in the description 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?

It gives clear context for when to use it: to discover which values actually work as filters and to see which chambers or subjects touch a topic 'antes de gastar una consulta'. There is no explicit when-not or named-alternative guidance, but the intended moment of use is well conveyed.

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 only supply readOnlyHint and openWorldHint; the description adds substantial non-obvious behavior: the appellant's brief is appended after the judgment and can occupy up to 58% of the document, the dispositive reasoning lives under «Réponse de la Cour» or «Mais attendu que», the citation protocol (French verbatim first, labelled working translation second), and the degraded-response path for non-Cassation courts. This is exactly the context annotations cannot carry.

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 purpose is front-loaded in the first sentence and each warning targets a real misuse (citing the losing lawyer's brief, presenting a translation as authoritative, treating French law as Dominican). The heavy emoji marking and repeated ⚠️ blocks make it noisier than necessary, but the content is not padding.

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

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

With no output schema, the description correctly carries the burden of describing the return shape (full text, ECLI, visas, map) and the partial-result case. It does not restate the mode/parameter interactions that the schema already covers, leaving a small gap on how the map mode output should be read.

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 75% and the schema already documents «modo» with its enum, «buscar» as French-only and required in search mode, and «ventana» bounds. The description only alludes to the map concept in its first sentence and adds no format or interaction detail beyond the schema, so the baseline of 3 applies.

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 opening sentence names the exact resource and its payload: the full text of a French decision plus its ECLI, visas and a map of where the court versus the party speaks. That is specific enough to separate it from the sibling search tool buscar_jurisprudencia_francia (which finds identifiers) without opening either schema.

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 gives a concrete failure-mode exclusion — the official API only documents reading for the Cour de cassation, so Conseil d'État or Conseil constitutionnel decisions may return a fiche without text — which steers the agent's expectations before calling. It stops short of explicitly naming the sibling to use first to obtain the identifier, so it is clear context rather than full when/when-not/alternatives routing.

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 and openWorldHint, but the description adds substantial context beyond them: first call is slow because the PDF is downloaded/extracted, the PDF is a Gaceta Oficial cut that may contain adjacent decrees, aviso_cobertura signals partial search coverage, and decrees may modify/repeal others so vigencia must be checked. This is exactly the operational context an agent needs.

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?

Long, but front-loaded with the resource and doc_id requirement, then mode semantics, then warnings. The stacked ⚠️ blocks are dense yet each carries a distinct rule; only slight trimming is possible.

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 7-parameter, no-output-schema tool this is complete: it describes what each mode returns, the citation constraint, the PDF boundary problem, coverage warnings, and first-call latency. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning about how the parameters combine: no extra args yields the ficha (page count), articulo matches the «Art. N.-» heading rather than in-text mentions, and buscar returns pages plus context. It explains mode semantics that the flat schema does not convey.

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?

States a specific verb (leer) plus a precisely scoped resource (decreto o reglamento del Poder Ejecutivo, extraído del PDF oficial de la Consultoría Jurídica), which separates it from siblings like leer_norma_reguladora or leer_doctrina. It also enumerates the six operating modes, so an agent knows exactly what the tool returns.

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 tells the agent how to obtain the doc_id (buscar_decretos), which mode to use for which need, and gives a strong when-not: do not read a 100+ page reglamento whole, request estructura/articulo and read the answering chapter with desde/hasta. Also states the citation rules and the latency expectation.

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 and openWorldHint, but the description adds substantial behavior: first read is slow due to download/extraction (no retry), 120-page truncation is announced, coverage warnings mean search did not cover the whole work, and output fields carry attribution semantics (`es_cita`, `autor`, `es_aparato`, `seccion`, `aviso_citas`, `donde_aparece`). 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?

Front-loaded with purpose, then modes, then warnings; each warning is substantive rather than filler. It is long and repeats the 120-page limit already present in the schema, but the density and structure justify most of its length for a six-parameter, multi-mode tool.

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 no output schema, the description carries the full burden and does so: it explains what the ficha returns, what each mode returns, how page numbers relate to citations, and the meaning of attribution and coverage fields. An agent has enough to call the tool correctly and interpret its output.

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 100%, so the baseline is 3. The description still adds meaning beyond the schema: `articulo` recognizes the «Art. N.-» header but not in-text mentions or the índice, `buscar` is accent- and case-insensitive, and `desde`/`hasta` is capped at 120 pages. It stops short of explaining parameter interactions exhaustively, but the incremental value is real.

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?

States a specific verb and resource ('El texto de una obra de la biblioteca, por páginas') and explicitly names its sibling source ('el isbn13 que devuelve buscar_doctrina'), distinguishing reading from searching. The five modes are enumerated immediately, so an agent knows exactly what the tool does.

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?

Gives explicit routing: start with the ficha, use the índice with `desde`/`hasta` if available, otherwise use `buscar`. It also states exclusions (do not cite context from `buscar`, do not infer absence from a zero when `aviso_cobertura` is present) and names the sibling dependency buscar_doctrina.

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?

Goes far beyond the readOnlyHint/openWorldHint annotations: discloses the 120-page read cap and truncation behavior, first-call latency versus subsequent immediacy, the `aviso_cobertura` partial-coverage caveat (a zero is not proof of absence), and the citation-attribution flags (`es_cita`, `autor`, `es_aparato`, `aviso_citas`). It also warns that the returned PDF page is the one used in citations.

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?

Front-loaded with purpose and slug requirement, then organized by mode and by warning; almost every line carries decision-relevant information. It is long and somewhat repetitive in its warning block (coverage caveat stated twice, dual ⚠️⚠️ headings), which costs it a point but is defensible for a five-mode tool.

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?

No output schema exists, and the description compensates by naming the response fields that matter (`donde_aparece`, `aviso_cobertura`, `es_cita`, `autor`, `es_aparato`, `seccion`, `aviso_citas`) and how to interpret them. For a complex multi-mode reader, nothing an agent needs to call it correctly or report results honestly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real semantics the schema lacks: that parameters act as mutually exclusive modes (default = ficha), that `articulo` matches the «Art. N.-» header and not in-text mentions or the index, that `buscar` is accent/case-insensitive, and that `desde`/`hasta` should follow the índice.

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?

States a specific verb (leer/extraer el texto) and resource (una publicación del Centro de Estudios Constitucionales, por páginas, de su PDF oficial), and implicitly distinguishes itself from the search sibling by requiring the `slug` that buscar_doctrina_constitucional returns. An agent can tell it apart from leer_doctrina and buscar_doctrina_constitucional without opening a schema.

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?

Enumerates the five modes and the exact condition that selects each (sin más argumentos → ficha; `articulo`; `buscar`; `desde`/`hasta`; `pagina`), plus an explicit recommended workflow (empieza por la ficha, si hay índice usa desde/hasta, si no usa buscar). It also names the prerequisite tool that supplies the slug.

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 only supply readOnlyHint and openWorldHint, but the description adds genuinely non-structured behavior: the first read is slow (download + PDF extraction) while later reads are instant, and it explicitly says not to retry on slowness. It also discloses the scanned-PDF-without-text fallback and the citation policy (only `pagina`/`desde`/`hasta` output is citable; `buscar` context merely locates). This is substantial behavioral context 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?

Front-loads the resource, then the six modes, then the warnings, so the reader gets the essentials first. The long enumeration of regulators is somewhat heavy but is necessary to define scope precisely; otherwise nearly 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?

With no output schema, the description still characterizes what each mode returns (ficha = page count, `estructura` = headings with page and first article, `buscar` = matching pages with context, `articulo` = starting page). Combined with the latency, truncation, and scanned-PDF disclosures, an agent has everything needed to call 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot: it explains how parameters combine into distinct modes, that `buscar` results are locators rather than citable text, and that excessive ranges are silently truncated and reported. It does not add syntax or format detail beyond that, so it sits just above the baseline.

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?

States a specific verb and resource (returns the text of a regulator's norm, page by page, extracted from the published PDF) and enumerates the exact set of regulators in scope. It clearly distinguishes itself from the sibling buscar_normas_reguladores by naming it as the source of the `clave`, so an agent can route read vs. search without opening either schema.

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 enumerates six modes and the argument combination that selects each (no args = ficha, `estructura`, `articulo`, `buscar`, `desde`/`hasta`, `pagina`). It adds when-NOT guidance too: 'NO lo leas entero: pide la estructura o el articulo, y lee con desde/hasta solo lo que responde la pregunta.' Nothing about mode selection is left to inference.

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 and openWorldHint, so safety is covered; the description goes further by disclosing the actual payload (full text + ECLI + structural map) and flagging that search output is cataloguing, not the ruling's own words. It doesn't discuss length limits or truncation for very long resolutions, which is the remaining behavioral unknown.

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?

Front-loaded with what is returned, then two dense warnings that each carry operational weight. The trailing 'Doctrina persuasiva en RD' is cryptic and under-explained, the one phrase that doesn't clearly earn 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?

No output schema exists, and the description compensates by describing the returned structure (íntegro + ECLI + mapa). For a 4-parameter read tool with readOnly annotations this is nearly sufficient; only the 'ventana' window and behavior on exceptionally long rulings are left unaddressed.

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 75% and the schema itself documents modo's three values, buscar's conditional requirement and resolucion's accepted formats (STC 52/2026 or internal id). The description adds nothing parameter-specific, and 'ventana' is undocumented in both places. Baseline 3 for high-coverage schemas doing the heavy lifting.

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?

States a specific verb (leer), a precise resource (resolución del Tribunal Constitucional de España), and enumerates what comes back: texto íntegro, ECLI y mapa de Antecedentes/Fundamentos/votos particulares. That distinguishes it from the buscar_* siblings and from the other national leer_* tools without needing the schema.

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 warning 'Sin leer el texto no hay criterio que citar: la síntesis de la búsqueda es catalogación, no palabras del fallo' establishes the workflow position — read this before citing, don't cite search summaries. It stops short of naming the concrete alternatives (buscar_jurisprudencia_espana, resolver_referencia, obtener_texto_completo), so routing is implied rather than spelled out.

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 and openWorldHint, so the safety profile is covered. The description adds real context beyond that: the returned document contains a structural map marking where minority opinions begin, and an interpretive warning that the doctrine is persuasive in RD, never binding. It says less about size limits or pagination for full-text retrieval.

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?

Front-loaded with the most important fact (full text plus map), followed by two warnings that each earn their place. Four sentences, no filler, though the emphasis markers make it slightly dense.

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 read-only tool with no output schema, it adequately explains what is returned (full text plus a section map) and how to interpret it legally. The main residual gap is behavior on very long rulings and the relationship between modo='mapa'/'buscar' and result size, which is only covered inside the schema.

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 75% and the schema itself describes modo, buscar, ventana, and sentencia (including accepted reference formats like T-012/23 or a relatoría URL). The description adds nothing about parameters, so the baseline 3 is appropriate – the schema carries this dimension.

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?

States a specific verb and resource: full text of a Colombian Constitutional Court ruling, including the map of salvamentos and aclaraciones de voto. This clearly differentiates it from siblings like leer_decreto, leer_resolucion_espana, leer_decision_francia, and from the buscar_* search 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?

Gives clear context for when it matters ('sin leer el texto no hay criterio que citar') and implies the read-after-search workflow by noting that topic and summary come from the relatoría, not the Court. It does not, however, name a specific sibling search tool as the prerequisite step or state explicit 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 declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe external read. The description's one addition is what the call yields (PDF link plus cover page), which is genuinely useful since there is no output schema, but it omits access, availability, or failure behavior for older/future months.

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 short sentences with no filler, front-loading the resource and then the return value. Nothing needs to be trimmed.

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 single-parameter, no-output-schema tool, the description covers what it returns and that it is monthly, which is most of what is needed. It still leaves the key semantic link between the fecha argument and month selection unexplained, so an agent could call it with an arbitrary date without knowing whether that is valid.

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 100% and there is only one parameter, so the ISO date format is already documented in the schema. The description adds nothing about how fecha maps to a monthly bulletin (e.g. whether a mid-month date selects that month's edition), which is the one ambiguity an agent could get wrong.

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 a specific resource and action: a monthly judicial bulletin of the Poder Judicial, returning the PDF link and cover page. It is clear on its own, but it does not distinguish itself from the many buscar_*/leer_* siblings, so an agent cannot tell from the text alone why it would pick this over, say, obtener_texto_completo.

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?

There is no explicit when-to-use guidance and no mention of alternatives, despite 17 sibling tools. The monthly cadence is the only implicit usage signal, and nothing says whether to call this instead of the search tools or in combination with them.

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 only declare readOnlyHint and openWorldHint; the description adds substantial behavioral context beyond that: `criterio` refuses to return text (rather than dumping the whole document) when it cannot delimit the court's holding, PDF responses carry `pagina` marks, `buscar` windows carry `de_quien` and `no_citable_como_criterio`, and partial reads are resumable. It also discloses the real hazard (non-court text that mimics court reasoning) that governs correct use.

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?

Front-loaded with the purpose, then the citation warning, then mode-by-mode guidance. It is long, and the two measured-error anecdotes (the 29% passage, the 17-of-33 votos) are borderline, but they concretely justify the warning rather than padding, and each mode paragraph 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?

With no output schema, the description carries the return-value burden and does so: it names the returned fields (`de_quien`, `no_citable_como_criterio`, `pagina`, `leida`), explains what each mode returns and withholds, and covers all three input routes and the resume-on-partial-read behavior. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: the exclusivity/relationship of `id` vs `tc` vs `tse`, that `buscar` is mandatory only in `modo: "buscar"`, and that `criterio` is the citation-safe mode. It stops short of explaining `ventana` sizing tradeoffs, but the added routing meaning is real.

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 opening states the specific verb+resource (returns the text of a sentencia plus its structural map), and the four `modo` values are spelled out so an agent knows exactly which output shape it is requesting. It also distinguishes its three input paths (indexed `id`, TC PDF via `tc`, TSE PDF via `tse`), which separates it from the country-specific siblings like leer_sentencia_colombia or leer_resolucion_espana.

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 gives explicit when-to-use routing: `modo: "criterio"` for citing, `modo: "buscar"` for locating (not for blind citation), `modo: "mapa"` for structure only, and `tc`/`tse` for documents absent from the indexed text. It even covers the retry path when a response returns `leida: false`, and points to resolver_referencia's `como_leer` field as the signal for choosing the PDF route.

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?

With no output schema, the description carries the full return-semantics burden and does so: `encontrada`, `mismo_numero_y_dia`, `registro_oficial`, `como_leer`, `consultado`, and a three-way reading of `existe` (true = indexing gap, null = retry, false = reasonable to conclude it doesn't exist). It also warns that an official-register hit returns metadata and not text, so the model must not quote from it. This is far beyond what readOnlyHint/openWorldHint declare.

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?

It is long for a one-param tool, but nearly every sentence is operational and the core action is front-loaded in the first line. The warnings are repeated with emphasis ('NO digas que no existe' appears twice) and the emoji/caps formatting is noisy, which costs a point without undermining the 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?

A complex routing tool with three fallback sources and a rich result contract, yet the description covers source selection, field semantics, the sala ambiguity, the no-text-after-14/04/2026 edge case, and how to read a hit. With no output schema and no sibling covering this, nothing an agent needs to call it or interpret the result is missing.

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

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

Schema coverage is 100% and the single param is already described as 'la referencia tal como aparece citada', so the baseline is 3. The description adds real value by supplying accepted input formats for each corpus and, critically, an input precondition for classic prose: the sala must be included because each SCJ chamber numbers independently.

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?

States a precise verb+resource ('Convierte una referencia citada en el documento al que apunta') and enumerates the exact reference grammar it accepts: TC/0437/17, SCJ-PS-22-2005, classic prose, and norms like «Ley núm. 108-05». It explicitly separates itself from the sibling buscar_legislacion by noting that codes and Poder Judicial reglamentos live in other collections, so an agent can route without opening a schema.

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?

Gives an explicit use case ('comprobar que un precedente citado existe y es el que se dice, en vez de darlo por bueno') and spells out the escalation path: local index, then Clerk's own index, then the official TC registry. It names the follow-up tools (obtener_texto_completo, leer_doctrina) and says which public register it does NOT cover, which is exactly the when-to-use/when-not guidance the dimension asks for.

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