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

With no annotations, the description carries the full burden and discloses useful behavior: search ignores accents and capitalization, returns offsets and extracts, enforces context and match limits, and indicates hay_mas when more occurrences remain. It does not mention authentication, rate limits, or error behavior, but those are less critical for this read-only search tool.

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 behavior before the argument and return details, and the Args/Devuelve structure makes scanning easy. The examples and range details earn their place by removing ambiguity.

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?

Covers what the tool does, all parameters, and the return shape even though there is no output schema. It also supplies the offset-to-texto_completo workflow, which is the key operational context for using the 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 description coverage is 0%, so the description must compensate, and it does: it documents all four parameters with meaning, examples, and constraints, including id format, texto length, contexto range and default, and max_matches range and default.

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: searching a word or phrase inside the full text of a specific SPIJ norm. It also distinguishes itself from reading the whole text by explaining the offset-based occurrence result and referencing texto_completo for surrounding context.

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?

Makes the intended use clear: ideal for jumping to specific sections without reading all text. It names texto_completo as the follow-up tool for reading around a match, but it does not explicitly say when to prefer buscar_normas or other siblings instead.

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 annotations, the description carries the full burden and does so: it discloses that tomo is ignored by the index, that organismo filters locally by scanning up to 5 SPIJ pages, and it documents practical failure modes ('sugerencias' on zero results, 'organismos_disponibles' when no match under the requested organismo). This is unusually thorough behavioral context beyond a bare verb+resource statement.

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 purpose followed by well-separated Args and Devuelve blocks make it easy to scan. It is long, but the length is justified by the 11 undocumented parameters and absent output schema; only minor redundancy between the tomo/organismo notes.

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 supplies the return contract itself (ok, total, organismo, escaneadas, filtrados, normas, siguiente_start, plus conditional sugerencias / organismos_disponibles). Combined with per-parameter guidance, an agent has everything needed to invoke and interpret the call.

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

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

Schema description coverage is 0% and there are 11 parameters, so the description must compensate fully. It documents essentially every parameter with format hints and quirks: consulta syntax rules (implicit AND, no quotes/OR, wildcard *, start with 1-2 words), expediente formats like '03209-2024-PA/TC', AAAA-MM-DD dates, orden codes, and sumilla_chars=0 meaning unlimited.

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 (jurisprudencia en el SPIJ), and scopes it with concrete content types (TC, cortes, precedentes, sentencias). An agent can distinguish it from the sibling buscar_normas 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 routes usage: warns that 'tomo' is not applied by the index and that organismo is the correct filter path, and points to listar_filtros(categoria='materias') for enumerating values. It also names detalle_norma / texto_completo as the follow-up tools for retrieving full text, giving clear when-to-use and next-step 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?

No annotations exist, so the description carries the full burden, and it does: ordering defaults, pagination semantics (start multiples of 10, paginas up to 10), the exact shape of the zero-result response (nota + sugerencias with shortened queries), and the ambiguity/candidate behavior for partial dispositivo values.

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 one-line purpose followed by clearly separated Args and Devuelve sections; nearly every sentence adds an example or a warning. It is dense and long, but the length is justified by 12 undocumented parameters and no output schema.

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 annotations, no output schema, and 0% schema coverage across 12 parameters, the description supplies everything an agent needs: input semantics, return fields, pagination, ordering, and error/empty-result 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%, yet every one of the 12 parameters is documented with format, examples, and pitfalls ('200-2026-EF', 'sin prefijo Nº', AAAA-MM-DD, sumilla_chars=0 means no limit, start=(N-1)*10). This fully compensates for the empty 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 ('Busca normas legales en el SPIJ') with the scope of the corpus (normas generales, administrativas). The resource distinction from buscar_jurisprudencia is implicit in the terminology, and it explicitly points to detalle_norma and listar_filtros for adjacent needs.

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 concrete query-construction rules (AND semantics, no quotes/OR, trailing wildcard, start with 1-2 words) and routes the agent to siblings: listar_filtros for ambiguous dispositivo, detalle_norma for the full sumilla. It also explains fallback behavior when a numeric law is not indexed as its own record.

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 annotations, the description carries the full behavioral burden and does well: it discloses the return shape (texto sans HTML, total_caracteres, texto_truncado, siguiente_offset) and the truncation/continuation behavior. It stops short of stating permissions or rate limits, but for a read tool that is minor.

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?

Structured as Args/Devuelve/Nota with the core action front-loaded. Each section earns its place, though the closing 'Nota' partly repeats the offset/desde_final guidance already given in Args, adding mild 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?

No output schema and no annotations, yet the description documents parameters, return fields, and pagination. It is self-sufficient for correct invocation; only the lack of differentiation from the texto_completo sibling leaves a small gap.

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

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

Schema description coverage is 0%, so the description must compensate, and it does fully: id format example 'H1453062' plus its source, offset as character index with 0=start, max_chars with 0=default limit and truncation behavior, and desde_final semantics with a rationale for judicial sentences.

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 ('Devuelve los METADATOS y el TEXTO de una norma del SPIJ por su id') and clarifies where the id comes from (buscar_normas). It is clear what the tool does, though it does not explicitly differentiate itself from the similar sibling 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?

Gives strong operational guidance: how to page long texts via offset/desde_final, that desde_final targets the trailing 'RESUELVE' of judicial sentences, and a closing note to read in ranges when the text exceeds context. No explicit when-not-to-use versus siblings, but the pagination context is clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses the 150-heading cap, the 'siguiente_encabezado' pagination key, that offsets index the same canonical text as texto_completo, and the empty-result case for prose (TC sentencias). It omits auth/rate-limit or cost context, keeping it below 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?

Front-loaded purpose, then Args and Devuelve sections. The return listing is somewhat verbose but earns its place given there is no output schema. Little waste overall.

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, so the description correctly documents the return shape (ok, id, url_web, fuente, totals, encabezados list) and the truncated/empty cases. Combined with the sibling routing hint, an agent has everything needed to call and interpret it.

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% and the single required param is undocumented in the schema, but the description compensates: 'id' is defined as the SPIJ identifier with an example ('H1453062') and it notes the id comes from buscar_* tools. That is enough to call the tool correctly.

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 index of headings of a SPIJ norm, including each heading's offset. It is clearly distinguishable from siblings like texto_completo (full text) and buscar_en_norma (search), so an agent can route correctly.

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?

Explains the intended workflow — use the returned offsets to read specific sections via texto_completo(id, offset=X, max_chars=N) — and names fallbacks (buscar_en_norma or range reading) for prose norms with no headings. It does not explicitly contrast with detalle_norma or say when not to use it, so it stops short of a 5.

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 annotations provided, the description carries the burden and does well: it discloses the return shape ('ok' plus 'valores'), conditional behavior for omitted categoria and required tomo, and the exact-string nature of results. It does not explicitly state that the operation is read-only or mention error behavior, but the listed behavior is clear.

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 front-loaded with its purpose and then structured into Args, category explanations, and return values. It is appropriately detailed for a discovery tool, though the tomo requirement is repeated slightly between the Args section and the categoria breakdown.

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 0% schema description coverage, no output schema, and a two-param tool with conditional behavior, the description is complete. It documents both parameters, the return structure, valid category values, and how the output connects to sibling search tools.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It fully enumerates valid categoria values, explains the dependency of tomo on categoria='materias', gives an example tomo value, and describes the special summary behavior when categoria is omitted.

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: listing valid filter values for SPIJ. It also clarifies that returned strings are exactly the values accepted by buscar_normas and buscar_jurisprudencia, so an agent can distinguish this discovery tool from the sibling 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?

Explains when each categoria is relevant, that tomo is only used with categoria='materias', and that omitting categoria returns a summary. It also gives an alternative path for sectores when a value is missing. However, it does not explicitly frame the overall when-to-use versus when-not-to-use relationship with all siblings.

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 annotations, the description carries the full burden and does well: it discloses the primary route (documento word), the fallback route (texto del detalle), truncation behavior with siguiente_offset, and that desde_final returns the tail. It omits any note on permissions, rate limits, or failure modes beyond the word/detalle fallback.

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 core purpose, then structured Args/Devuelve sections that each earn their place. Slightly verbose in the route explanation, but no sentence is pure 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 and no annotations, the description enumerates every return field (ok, id, url_web, codigoNorma, fechaPublicacion, dispositivoLegal, texto, total_caracteres, texto_truncado, siguiente_offset) and explains pagination end-to-end. An agent has everything needed to call and consume this reliably.

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

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

Schema coverage is 0%, so the description must fully document the four parameters — and it does: id format with an example, offset as start character, max_chars with 0 = default and its link to siguiente_offset, and desde_final with the reviewing-decision rationale. This fully compensates for the empty schema 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?

States a specific verb+resource: returns the FULL TEXT of a norm or jurisprudence from SPIJ, which is clearly more than a summary. It distinguishes itself from the search siblings by noting the 'id' comes from buscar_*, but it never contrasts itself with closer siblings like detalle_norma or estructura_norma, leaving that boundary implicit.

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

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

Clear context: use it after buscar_* to fetch an id and retrieve the whole document. It also gives a concrete usage tip (combinar desde_final=True con max_chars=3000 para leer el RESUELVE de una sentencia). No explicit when-not guidance or statement about when detalle_norma would be preferable.

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