mkna: Ecuador's official documents

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

Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds behavioral detail about the return structure, including `sectors`, `families`, `without_documents`, and aggregated fields like `instrument_kinds`, `sectors_classified`, and `topics`, which goes beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-structured: it leads with the core purpose, then usage, then the return shape. While it packs many details, each sentence earns its place; it could be slightly trimmed but remains efficient.

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

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

Given there is no output schema, the description thoroughly explains the return values, listing all top-level fields and their subfields, and even covers edge cases like families without documents. This makes it fully adequate for an agent to call and interpret 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?

With 0% schema description coverage, the description fully compensates by explaining the `sector` parameter: '`sector` narrows to one group of families (e.g. 'ley', 'ejecutivo', 'control', 'local')' and that providing it adds extra fields (`publisher`, `stored`, `classified`, `kinds`). This gives meaning beyond 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?

The description opens with a clear statement of what the tool provides ('What exists: every publisher (family) with how many documents it has and how many have text.') and explicitly differentiates it from siblings by stating it's used to learn valid family keys before filtering `search` or `documents`. This gives a specific verb+resource and distinguishes it from related 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?

The description explicitly states when to call the tool: 'Call it to learn the valid `family` keys and the kinds each publisher prints before filtering `search` or `documents`, or to judge whether a missing answer means a gap in the corpus.' It also explains that `sector` narrows to a group, providing clear context for usage.

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?

Beyond the read-only/idempotent annotations, the description discloses substantive behavior: the returned edge shape (quote and page), direction-dependent fields, newest-first ordering for 'in' edges, the condition under which target_document_id appears, and the legal caveat that an amendment edge is evidence of a change rather than a statement of current law. 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?

The definition is front-loaded with a one-line purpose, then clusters parameters, then output details and caveat. It is dense but not bloated; each clause adds a distinct fact needed to call the tool correctly.

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 thoroughly, naming the fields for both directions, defaults, constraints, and a semantic caveat. An agent has everything needed to construct a correct invocation and interpret the result.

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

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

Schema description coverage is 0%, and the description fully compensates: it defines direction values and their meaning, enumerates all relation values, caps limit at 100, and identifies the document_id target through the 'this document' framing. Every parameter gains actionable meaning.

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

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

The opening sentence states the exact resource and action: what a document cites, amends or repeals, and the inverse direction. This makes it immediately distinguishable from the sibling content-retrieval tools (fetch, read, search) because it is explicitly about citation edges.

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

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

The description gives explicit selection guidance for direction ('out' vs 'in'), relation narrowing, and the limit cap, and it tells the agent to follow a target_document_id with fetch or read. It does not, however, explicitly contrast citations with search/catalog/documents for finding documents, so the when-not-to-use guidance is only partial.

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

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

Annotations already declare the tool read-only, non-destructive, and idempotent. The description adds substantial behavioral context: newest-first ordering, 20-per-page pagination, cursor handling, conditional fields (`text: false`, `pages`, classification, Court abstract), and the relation to `fetch`. This goes well beyond what annotations alone provide and does not contradict them.

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 the core purpose, then compactly covers filters, pagination, return shape, and next step. Every sentence adds necessary operational detail, and the structure makes the information easy to scan. Nothing is wasted or redundant.

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

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

Given the tool has no output schema and 8 optional parameters with no schema descriptions, the description is complete enough: it explains the return fields, conditional fields, pagination behavior, and how to proceed to `fetch`. An agent has sufficient information to call and interpret results correctly without needing external docs.

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

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

With 0% schema description coverage, the description must carry the parameter meaning, and it largely does: it names all eight parameters, notes they are optional, says one or comma-separated multiple values are allowed, and even gives the category enumeration. The remaining gap is the lack of value format specifics for `kind`, `family`, `sector`, `topic`, and date formats for `published_from`/`published_to`, but the 'Filters as in `search`' pointer and the explicit parameter list still make the tool usable.

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

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

The description opens with 'List documents newest first, without a query', which is a specific verb and resource, and immediately distinguishes this from query-based sibling `search`. The examples and filter list reinforce that the tool is a filterable list, not a full-text search or a single-document fetch.

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

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

The description clearly conveys the primary use case: listing documents by filters without a natural-language query, with pagination and a handoff to `fetch` ('Next: fetch one'). However, it does not explicitly state when to prefer `search` over this tool beyond the phrase 'without a query', nor does it list exclusions, so it stops just short of full 5-level 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?

Beyond the readOnly/idempotent/destructive annotations, the description discloses the two id modes, the 60,000-character truncation behavior with truncated: true and next pointing to read, and the passage-with-context semantics. It also details the metadata contents, including the citable publisher URL and cited_by count, adding substantial behavioral context.

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 the core purpose and then moves logically from input types to return fields to next steps. It is dense but every sentence earns its place; there is no filler, tautology, or superfluous repetition.

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 one parameter, no output schema, and five siblings, the description covers what to pass, what comes back, when truncation occurs, how to continue, and which sibling to use next. There is no material gap an agent would need to resolve elsewhere.

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

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

The schema only defines id as a string with zero description coverage, but the description explains that id may be a passage id from search results or a document id, and specifies the behavior for each. This fully compensates for the schema's silence and removes ambiguity about what value to pass.

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: 'Read one document, or one passage in its context, by the id search, documents or citations gave.' It also distinguishes itself from siblings by naming read as the continuation for more pages or articles and citations for what a document applies to or is changed by. An agent can immediately identify this as the single-item reader tool.

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

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

The description explicitly conditions use on possessing an id produced by search, documents, or citations, which tells the agent when fetch is the right call after those tools. It also routes onward: use read for more pages or one article, and citations for what the document applies to and what changed it. This gives clear start and follow-up context.

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?

Even though annotations already mark the tool as read-only and idempotent, the description adds rich behavioral detail: it returns verbatim text with `[p. N]` markers, `path`, `url`, and `truncated: true` with `next` when the window doesn't fit. This is exactly the kind of non-obvious behavior an agent needs beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then gives parameter guidance, then output/return behavior, then an alternative. Every sentence earns its place and there is no filler or repetition of the 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?

Given that there is no output schema, the description fully covers return values, pagination via `next`, truncation behavior, and alternative tool routing. It is complete enough for an agent to invoke the tool correctly with any of the valid parameter combinations.

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 carries the full burden of explaining parameters. It explains `document_id`, `page_from`, optional `page_to`, `article` (with concrete examples like 'Art. 15' and 'único'), and `max_chars` with its 40,000 cap and default. No parameter is left unexplained.

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

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

The description opens with a specific verb and resource: 'Read part of a long document: a range of pages, or one article.' It also clearly distinguishes this tool from `search`, which is for finding a phrase rather than paging through the document.

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

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

It explicitly states when to use which parameters: pass `document_id` with either `page_from` (optionally `page_to`) or `article`. It also names an alternative: 'To find a phrase in a long document instead of paging through it, use `search` with its `document_id`.' This leaves no ambiguity about selection.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description goes far beyond by detailing the return structure (results with specific fields, facets with counts), the 1,200-char text limit, the limit <=20 cap, sorting options, and the presence of abstracts for Court rulings. It also explains that facets can be used to narrow subsequent searches, providing actionable behavioral context that annotations do not cover.

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 well-structured: a clear opening purpose, then query guidance, then filters, then return values, then next steps. Every sentence adds value—no fluff or repetition. It is appropriately detailed for an 11-parameter tool and front-loads the most critical information (purpose and primary usage) before diving into specifics.

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 tool with 11 parameters, no output schema, and no parameter descriptions in the schema, this description is exceptionally complete. It explains all parameters, the exact output format, facet usage, sorting, limits, and even the recommended follow-up action (fetch). An agent has everything needed to call the tool correctly and interpret results without ambiguity.

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 carries the full burden of parameter documentation. It explains every filter (family, kind, category, sector, topic, published_from/to, document_id, sort, limit) with examples and normalizations, and even advises on query language effectiveness. This fully compensates for the missing schema descriptions and adds meaning beyond the raw titles.

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 ('Find') and a precise resource ('passages in every document Ecuadorian public institutions publish'), and adds the directive 'Start every question here,' which clearly distinguishes it from siblings like catalog, documents, and fetch. An agent knows exactly what this tool does and when to reach for it.

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

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

The description explicitly tells the agent to start every question here and to follow up with fetch on the top results, giving clear when-to-use guidance. It does not explicitly contrast with catalog or documents, but the 'start here' instruction strongly implies this is the primary search entry point, which is adequate for selection.

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