Es la hora de la verdad (Congreso de los Diputados)

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

Annotations already cover read-only, idempotent and non-destructive behavior, so the bar is lower. The description goes beyond them by disclosing the response payload (url, atribucion) and the CC BY 4.0 obligation to cite and link the source — meaningful operational context. It omits pagination behavior around the limite parameter.

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 sentences, front-loaded with the purpose and scope, then the return/attribution note. No filler, though the attribution clause is slightly wordy.

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 usefully documents the return fields (url, atribucion) and the licensing requirement, plus scope and filters. Only pagination behavior is left unaddressed, which is a minor gap for a filtered search.

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 60%: nombre, provincia and grupo are documented in the schema, while legislatura and limite are not. The description restates the filterable fields but adds no syntax or format detail, and says nothing about limite. Baseline 3 is appropriate when the schema carries most of the burden.

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 (diputados), enumerates the filterable fields (nombre, provincia, grupo, legislatura), and constrains scope to those with a web profile (XIV/XV legislature). It is clear what the tool does, though it does not explicitly contrast itself with siblings like ver_diputado (single-record view) or buscar_votaciones.

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

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

The description implies this is the multi-criteria search tool by listing its filters, but never states when to use it versus ver_diputado or the other sibling search/view tools, nor any exclusions. Usage is inferable but not 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 readOnly/idempotent/non-destructive/closed-world, so the description only needs to add context — and it does: the catalog is a filtered subset of all votes, results come back most-recent-first with 'texto' acting as a relevance signal, and every response carries 'url' and 'atribucion' with a CC BY 4.0 citation obligation. Rate limits and error/empty-result behavior are not covered, keeping it short of 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?

Four sentences, front-loaded with purpose, then scope and ordering, then the catalog restriction, then the attribution obligation. Dense but each sentence carries distinct information; the licensing sentence is the longest and could be tightened, but nothing is 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?

No output schema exists, yet the description explains the return set (ordering, 'texto' ranking, 'url'/'atribucion' fields) and warns about the limited catalog plus where the rest lives. For an 8-parameter, all-optional read tool that is close to sufficient; only pagination/limit behavior and empty-result handling are left implicit.

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 only 50% schema description coverage, the description carries real weight: it enumerates the searchable axes (palabras, tema, legislatura, resultado, fechas), mapping to texto, tema, legislatura, resultado, desde and hasta, and adds semantics the schema lacks by noting that 'texto' also drives relevance ranking ('las más ajustadas a la búsqueda'). 'limite' and 'pagina' are left unexplained, which is a modest gap.

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 votaciones del Pleno del Congreso de los Diputados') plus the scope (legislaturas XIV y XV, desde febrero de 2020) and the searchable dimensions (palabras, tema, legislatura, resultado, fechas). It does not explicitly contrast itself with the sibling 'ver_votacion' (list vs. detail), so an agent must infer the split between the two 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?

Explicitly delimits when the tool applies ('Solo las votaciones con ficha en la web: votaciones finales de leyes, convalidaciones de reales decretos-leyes y las que tienen resumen') and routes everything else (enmiendas, mociones…) to a named alternative, the portada search engine with its URL. That is genuine when/when-not guidance with an alternative, not just implied 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?

Annotations already declare read-only, idempotent, non-destructive, and non-open-world behavior. The description adds useful context beyond that: the response includes a source URL and an attribution requirement under CC BY 4.0, which is a concrete behavioral/legal constraint an agent should respect.

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 lists return fields and the attribution requirement. It is dense but not repetitive, and every sentence earns its place; a tighter structure with bullet-like segmentation would improve readability.

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?

There is no output schema, so the description must explain what the response contains, and it does: group and constituency by legislature, votes recorded, abstention and dissent counts, specific dissenting votes, plus source URL and attribution. For a one-parameter read-only tool with secure annotations, this is complete enough for correct invocation and use.

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 sole parameter 'diputado' is fully documented there with examples. The tool description adds no additional meaning about the parameter, so the baseline of 3 is appropriate when the schema does 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?

The description clearly states it returns a detailed record ('Ficha') for a specific deputy, listing group, constituency, voting participation, and dissent counts. This distinguishes it from a search tool, but it does not explicitly name or differentiate itself from siblings like buscar_diputados or voto_de_diputado.

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?

Usage is implied by the noun phrase 'Ficha de un diputado' and the listed contents, so an agent can infer it retrieves a single deputy's profile. However, there is no explicit when-to-use guidance, no when-not-to-use, and no named alternatives, leaving the agent to infer routing from sibling names alone.

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/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: every response carries a 'url' and an 'atribucion', and the CC BY 4.0 licence obliges the caller to cite and link the source; it also disclaims that the match test is not a voting recommendation.

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 main purpose is front-loaded, but the entry is a dense, comma-chained block that mixes content inventory, the match test, attribution rules and licensing into one breath. The licence/attribution sentence earns its place, but several clauses (the test description, program status) could be tightened.

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 optional parameter, no output schema and full annotation coverage, the description is largely self-sufficient: it explains the returned fields ('url', 'atribucion') and the conditional provincial payload. Only the absence of routing guidance against siblings keeps it from a 5.

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% for the single 'provincia' parameter, so the baseline is 3. The description goes beyond the schema by explaining what changes when a province is supplied (deputy/senator counts and BOE-published candidacies), adding real semantic value.

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 names a specific resource (the 29N general elections) and enumerates concrete payloads: the official calendar with per-deadline status, provincial seat allocation, candidacies, program status, and the vote-match test. It is clear what the tool returns. However, it never distinguishes itself from overlapping siblings such as ver_programas_29n (program status) or ver_provincia (provincial data), so it falls short of a 5.

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?

Usage is only implied through the content listing and the conditional clause 'si se indica una provincia'. There is no explicit statement of when to call this tool versus ver_programas_29n or ver_provincia, and no when-not guidance, leaving the agent to infer routing from the data it returns.

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 this a safe, idempotent read (readOnlyHint, idempotentHint true, destructiveHint false), so the bar is lower. The description adds real context beyond them: results come in alphabetical order, contain literal quotes with no summaries or evaluations, and each response must carry 'url' and 'atribucion' under the CC BY 4.0 license.

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 fallback rule are front-loaded, and the licensing/attribution note is useful. It is somewhat run-on and packs several clauses into one long sentence, but no sentence 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?

With no output schema, the description carries the burden of describing returns (quotes, document links, voting links, url, atribucion) and does so. An agent knows what a call yields in every parameter combination, so nothing material 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 tema enum is self-describing, so baseline would be 3. The description goes further by explaining the semantics of omitting both parameters (returns party and topic lists) and clarifying that a party is matched by name or acronym, adding meaning beyond the schema text.

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 with scope: returns the 29-N electoral programs of parties holding seats at dissolution, with official-document links and literal quotes by topic. This is clearly distinguishable from siblings like ver_elecciones_29n or buscar_votaciones, and the no-topic/no-party fallback behavior is spelled out.

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 operating conditions — pass tema and/or partido for program content, pass neither to get the lists of parties and topics — and explains that each party also carries a link to its group's Congress votes. It does not name an alternative sibling or state exclusions, so 4 rather than 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?

Annotations already establish readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds genuinely useful context beyond that: every response embeds a «url» backing the data plus an «atribucion» field, and it explains the CC BY 4.0 attribution/linking obligation the caller must honour. That licensing constraint would be invisible otherwise.

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 sentences, front-loaded with the core content before the licensing caveat, and no filler. It is dense but slightly overloaded with legislative references (XV/XIV, Real Decreto 806/2026) that could have been tightened.

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 does the work of stating the response contents (legislature seats, election seats, deputies, plus url and atribucion). What it omits is failure behaviour for an unrecognised province name and any note on how substitutions are represented.

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 single parameter already documents itself with examples («Zaragoza», «Ceuta»). The description adds no further semantics about the parameter, such as accent handling or whether official spellings are required, so the baseline of 3 is correct.

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 names a specific resource (a circunscripción/provincia) and enumerates exactly what is returned: seats in the XV legislature, seats for the 29-N-2026 general elections, and its deputies in the XV and XIV legislatures with substitutions. This is clearly distinguished from person-oriented siblings such as ver_diputado or buscar_diputados without needing to open 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?

The usage is implied: you supply a province name and get that constituency's data. However, there is no explicit when-to-use guidance, no statement of what alternatives exist (e.g. ver_elecciones_29n for election-wide data), and no prerequisites or 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely new behavioral context: every response carries «url» and «atribucion», the CC BY 4.0 license obliges citing and linking the source, and AI-generated summaries are flagged as such. It does not cover response shape limits or errors, but it adds real value 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?

Two sentences, front-loaded with the payload contents and followed by the attribution obligation. The long enumeration is justified because no output schema exists, though the density is high and some list items could 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?

With no output schema, the description must carry the return contract, and it does: it enumerates the record's fields, the presence/flagging of AI summaries, and the url/atribucion fields. For a single-resource read-only tool whose annotations cover safety, nothing an agent needs to call 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?

One required parameter with 100% schema description coverage, including the accepted format example (XV-88-85) and the alternative of passing the page address. Per the rules, high coverage sets the baseline at 3; the description adds no parameter-level information beyond what the schema already states.

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 a specific resource (a single votación) and enumerates exactly what the full record contains: result, count, per-group vote, defectors, absentees, plain-language summary, norm, sources and link. That is far more than a restatement of the title. It does not explicitly contrast itself with the close sibling voto_de_diputado (individual deputy vote) or buscar_votaciones, so it stops short of a 5.

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?

Usage is only implied: an agent infers it should call this once it has an id and wants the full detail page rather than a search result. The id's provenance is stated in the schema description, not the tool description. No when-not-to-use or explicit alternative routing is given.

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 safe read-only/idempotent profile, and the description adds real value beyond them: it enumerates the possible vote outcomes and discloses a licensing obligation (CC BY 4.0) requiring attribution and source linking, plus the returned «url». This is useful operational context a caller would otherwise not know.

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?

Content is front-loaded: what is returned, then per-response fields and the attribution rule. Two dense sentences with little waste, though the attribution clause runs on.

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 compensates by naming the returned fields (vote, group at the time, majority divergence, url, atribucion), which is exactly what an agent needs to use the result. It stops short of stating error/missing-record behavior, a minor 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?

Both parameters are documented at 100% coverage in the schema (name/id/ficha URL for the deputy and votación), so the schema carries the semantics. The description adds nothing about accepted identifier formats or matching behavior, meriting the baseline score.

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 a specific verb+resource (a deputy's vote in a specific votación) and enumerates the answer's shape (Sí, No, Abstención, No votó, group, majority divergence). It is clearly a fine-grained lookup, distinct from session-level siblings like ver_votacion, but it never names the sibling it must not be confused with.

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?

Usage is only implied: 'given a deputy and a votación, return their vote'. There is no explicit statement of when to pick this over ver_votacion (whole-session results) or ver_diputado (profile), and no prerequisites for the two required inputs.

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