Dapper

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

The description adds substantial behavior beyond the annotations: it consumes paid quota, returns an async job taking 4–15 minutes rather than a report, the submitted title is later replaced, and duplicate requests deduplicate instead of charging again. These details align with the destructive and idempotent annotations and are critical for 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?

Despite covering auth, quota, async polling, title replacement, and retry semantics, the description is tightly organized and front-loads the most important warnings. Every sentence provides operational value.

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 an output schema present, the description does not need to document return fields. It still explains the job-vs-report distinction and polling path, which is the essential context for invoking this async, quota-consuming 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 100%, so the schema already documents each parameter well. The description adds meaningful cross-parameter semantics: title is only provisional, searches should use id or key_word, is_public affects separate budgets, and duplicate detection depends on term, window, and visibility.

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 uses a specific verb and resource: it asks Dapper to monitor a topic on X and Google Trends and write a report. It clearly distinguishes creating a listening from polling it with list_listenings and checking quota with get_listening_quota.

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 states explicit prerequisites and conditions: browser login instead of API key, confirm=true required, quota consumption, polling via list_listenings(id=...), and quota checking via get_listening_quota. It also explains safe retry behavior versus a genuinely new term.

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 cover the safety profile (readOnly=false, destructive=true, idempotent=true), and the description adds substantial context beyond them: browser-login auth rather than an API key, a per-account cap with a named error code, and the fact that the write is immediate while list_my_followed_bills reads a lagging replica. That last point prevents an agent from wrongly concluding the follow failed.

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 mutation plus auth caveat, then usage, then failure mode, then read-after-write caveat — a sensible ordering with no filler sentences. The dashboard clause in the second sentence is mildly redundant with the list_my_followed_bills reference but earns its place as disambiguation.

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 two-parameter mutation with an output schema, everything an agent needs is present: auth model, default behavior, cap and error semantics, and staleness of subsequent reads. No gaps remain that would cause a misinvocation.

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 adds real meaning by contrasting notify=true (notifications on) with notify=false ("follows it quietly"), which is a consequence the schema's terse one-liner does not convey. bill_id is left entirely to the schema, which already says it comes from list_bills.

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 (adds a bill to this user's watchlist) and explicitly ties it to the sibling list_my_followed_bills as the same list, with the dashboard as an external referent. An agent can separate it from list_my_followed_bills and unfollow_bill 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?

"Use it when someone asks to follow, track or watch a bill" gives the triggering intent in the user's own vocabulary, and the notify default/override is spelled out. It also gives the failure path (cap → FOLLOW_LIMIT_REACHED, retrying will not help, must unfollow first), which implicitly routes to unfollow_bill.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description earns credit for disclosing the ingestion-vs-origin trap, Chile-only coverage for by=origin, and that null keys are a coverage gap rather than an 'unknown' category. It does not mention result ordering, bucket limits, or what happens with no filters applied.

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 and the list_bills contrast before diving into per-value caveats, so an agent can stop reading early if it just wants the gist. The null-bucket explanation is stated twice (once for origin, once at the end), which is the one redundant beat.

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?

An output schema exists, so return shape needn't be described; the description instead covers the non-obvious risk in a grouped aggregate — trusting a bucket label. With zero required params and 100% schema coverage, nothing an agent needs to invoke 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 the baseline is 3, but the description adds real meaning to the enum beyond the schema's bare list: status is resolved to the latest tramitación's state, type to ley ordinaria/acto legislativo, source to ingestion origin, and origin to Moción vs Mensaje with an explicit 11-country coverage caveat. That is substantive disambiguation of the one parameter that determines the whole result.

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: counts of bills bucketed by one dimension, scoped to any filter list_bills accepts. It explicitly contrasts itself with list_bills by noting the alternative is paging every matching row and tallying by hand (4,088 rows at 50/page), which lets an agent pick the right tool 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 concrete triggering questions ('¿cuántos se aprobaron?', '¿cuántos por tipo?') and names the sibling it replaces. It also states the condition under which a specific group-by is misleading ('source is where Dapper ingested the record, NOT the bill's constitutional origin') and points to the correct alternative (by=origin, Chile only).

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 readOnly, idempotent, closed-world, non-destructive, so the safety burden is covered. The description adds genuine behavioral context beyond them: the response is heavy (tens of KB per row) and semantically dense, which warns the agent against bulk-fetching. It does not discuss latency limits or error behavior, keeping it out of the 5 range.

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 tight paragraphs: first the payload and its sibling contrast, then the identifier provenance. Nothing is repeated from annotations or the schema, and the most decision-relevant facts come first.

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?

An output schema exists, so return-value documentation is not strictly required, yet the description still characterizes the payload usefully. Combined with annotations covering safety and 100% schema coverage on parameters, an agent has everything needed to call it correctly; only the two optional filter parameters are unaddressed in prose.

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 earns a bump by explaining that `id` is precisely the same uuid surfaced by list_committee_minutes, establishing cross-tool provenance the schema alone does not. The optional country_id/country_code filters are left entirely to the schema, including the deprecated-alias warning.

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 (one board minute) and enumerates the exact payload — what was asked, background, board's concept, decision text, label-update flag — so the agent knows the shape of the answer before calling. It also explicitly distinguishes itself from list_committee_minutes as the detail counterpart to that list 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 alternative is named explicitly and the selection rule is stated: list_committee_minutes omits these fields because they run to tens of KB per row, so this tool is the detail fetch. It stops short of an imperative when-to-use/when-not-to-use rule, but the routing signal 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?

Annotations only cover the read-only/idempotent safety profile, and the description adds substantial non-derivable behavior: no API key required, domains silently withheld (votes, interventions) rather than empty, `not_covered` vs `stale` distinction, per-country publishing-rhythm baselining, and the rule that `feeds` can make a pair stale via any single counted source. These are exactly the traps that would cause a wrong report.

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 core purpose and status set are front-loaded in the first sentence, and each subsequent paragraph covers a distinct semantic trap rather than restating. It is long, and some output-interpretation detail could sit in the output schema, but 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?

For a single-param read tool with an output schema, the definition covers what the schema cannot: meaning of each status, null vs zero for `search_corpus`, why domains are omitted, and how `counted: false` feeds behave. An agent has everything needed to call it and interpret the result 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 100% and the single `country_code` param is fully documented in the schema, including ISO alpha-2 and legacy numeric acceptance. The description adds only the scoping emphasis ('ONE country') and incidental country mentions (PE, AR, VE, GT, DO), which are illustrative rather than parameter guidance; 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 verb and resource ('freshness status ... for every data domain in ONE country') and enumerates the exact status values returned. It also explicitly disambiguates from the sibling: 'the same computation as get_health, scoped down,' so an agent can choose between them 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 concrete when-to-use triggers ('before a bulk pull', 'when a query comes back thinner than expected') plus when-not reasoning ('a stale domain means the ingestion pipeline is behind, not that you queried wrong'). It also routes the agent elsewhere for withheld domains ('query their endpoints directly') and distinguishes `search_corpus` from freshness, telling the agent to use record listings instead of concluding a topic is absent.

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 readOnly/idempotent annotations: warns that text is third-party content and must not be treated as instructions (prompt-injection guidance), discloses uneven ~125k-document coverage and that `text_available` and the `coverage` block disambiguate empty results, and explains server-side truncation and chunk-seam artifacts.

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 returns and the key differentiator before the caveats. It runs several paragraphs, but nearly every sentence carries operational value; the injection warning and coverage caveat could be tightened slightly.

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 an output schema present and annotations covering safety, the description supplies exactly the missing context: domain/id resolution, truncation behavior, coverage gaps, and the interpretive rules for reading the response. Nothing an agent needs to call or interpret it correctly is absent.

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 schema already documents all five parameters including enums and defaults. The description adds some behavioral meaning (raise `max_chars` for the whole articulado, bill documents labelled by tramitación step) but leaves `order` and `document_limit` entirely to the schema, so it lands at 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+resource ('full extracted text of the source document(s) behind one record') and enumerates the domains covered. It explicitly differentiates from every sibling by noting they 'stop at title, summary and a link to a PDF,' so an agent can pick this tool without opening another 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 a concrete use case with an example question (article-by-article reading and comparison) and explains the bill case where comparing versions means comparing two of these. The exclusions are implied through the sibling contrast rather than stated as explicit 'do not use for X' rules.

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

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

Annotations already declare readOnlyHint, idempotentHint, and closed-world behavior, so the safety profile is covered. The description adds genuine context beyond that: the response includes a readable `body_text` while raw editor HTML is deliberately withheld, and the content is curated rather than scraped — both facts an agent needs to interpret results correctly.

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 content description is front-loaded, and the second sentence about body_text versus raw HTML is informative rather than filler. The parenthetical about 'hundreds of bytes of `<p style=...>`' is slightly verbose but justifies the design decision, so it mostly 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 an output schema present, the description need not enumerate return fields, and it appropriately highlights only the notable one (`body_text`). Parameters are fully documented in the schema. The remaining minor gap is the absence of explicit routing to or from `list_explainers` in the description text.

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 `id`, `country_id`, and `country_code` are fully documented in the schema itself. The description adds no parameter-level detail beyond what the schema already provides, so the 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?

The description states specifically what is returned: the full editorial explainer covering what the thing is, how it works, and who regulates it, authored by Dapper's editorial team. The word 'full' implicitly contrasts with the truncated list view, though no sibling tool is named directly in the description. An agent can identify the resource and content type 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?

The description gives citation/attribution guidance ('cite it as Dapper's own explainer rather than as a primary source'), which is useful but is about how to present results, not when to call this tool versus alternatives. There is no explicit when-to-use or when-not guidance; the id source ('from list_explainers') appears only in the schema.

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?

Despite annotations already covering read-only/idempotent behavior, the description adds substantial operational context: what stale means versus not_covered, why some domains are withheld, how feeds determine pair-level staleness, and how search_corpus differs from freshness. This rich disclosure goes well beyond structured hints.

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 usage guidance, then organized into clear paragraphs by concept. It is somewhat long for a no-parameter tool, but nearly every sentence carries useful disambiguation rather than 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?

Given that an output schema exists, the description need not enumerate return fields. It provides the interpretive context needed to understand statuses, withheld domains, feeds, and search_corpus, making the definition complete for correct agent 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?

The tool has zero parameters, so there is no parameter semantics to explain. Baseline 4 applies; the description appropriately focuses on output interpretation rather than input usage.

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

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

The description clearly states that the tool reports freshness status per domain and country, and it explains key status semantics. However, it does not explicitly distinguish itself from the closely named sibling get_country_health, leaving some ambiguity about which health-oriented tool to choose.

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 guidance ('before a bulk pull or when a query looks stale') and actionable alternatives for domains not covered ('Query their endpoints directly') and for absent search_corpus entries ('use the record listings'). This is exactly the routing information 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 already cover the safety profile (read-only, idempotent, closed-world), and the description adds substantial context beyond them: results reflect OBSERVED practice in the ingested record, not the reglamento; a missing stage means 'not recorded in the window', not 'doesn't exist'; and window_days bounds the observation. These epistemic caveats materially change how an agent should present results.

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 and return shape come first, then usage triggers, then caveats. Dense and mostly waste-free, though the window_days sentence at the end repeats schema guidance and the length is near the upper bound for comfortable scanning.

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 three-parameter tool with a full output schema, the description covers everything an agent needs: what the answer contains, which questions it answers, how far back the observation reaches, and the interpretive limits to pass on to users.

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 prose reiterates window_days' default and the widening advice already present in the schema, and never mentions min_updates, which the schema documents on its own. It adds little semantic value beyond the structured fields.

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 (retrieves a country's legislative process) and enumerates exactly what comes back: chambers, in-use bill types, and an ordered stage sequence with update and distinct-bill counts. It also names the data source (Dapper's tramitación records), which distinguishes it from descriptive/legal-text siblings like get_explainer or get_bill_breakdown.

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 trigger questions ('what happens next', 'how many debates', 'is it bicameral') so the agent knows when to reach for it. Explicitly states what it is NOT for — deadlines, majority thresholds, article numbers — and names the alternative source (the chamber's own reglamento), which is exactly the when-not guidance most definitions lack.

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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: the two budgets are independent and non-transferable, requests against an exhausted budget are rejected, and a listening takes 4-15 minutes. That last detail matters for the agent's expectations after calling create_listening. Missing only rate-limit or reset-window information.

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 answer in the first sentence, then adds two short supporting notes. Slight waste in the colloquial Spanish aside («me quedan 3»), which is evocative but costs a clause; otherwise every sentence carries information.

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 zero-parameter read with a full output schema and rich annotations, this is sufficient: it explains what the two counters mean, that they cannot be combined, and the consequence of exhaustion. Nothing needed 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?

The tool takes zero parameters, so the baseline is 4. The description's explanation of public_remaining vs private_remaining adds meaning to the returned fields even though an output schema exists.

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: how much social-listening quota the user's company has left, split into two budgets. That is clearly distinct from list_listenings (which lists actual listenings) and create_listening. It doesn't, however, differentiate itself from the sibling get_usage, which an agent could plausibly confuse it 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 implied rather than stated: by noting that a request against an exhausted budget is rejected, it hints the tool should be checked before create_listening, but it never names that sibling or says 'call this before requesting a listening.' The guidance on answering 'how many are left' per kind is useful but is about interpreting results, not about when to select this tool.

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 read-only, idempotent, closed-world safety, so the description adds the details annotations cannot: it requires a browser login, it mirrors the dapper://me resource, and the returned default country explains the fallback behavior of an omitted country_code elsewhere. No return shape discussion is needed because an output schema exists.

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 who/what, then usage, then auth. The opening sentence is dense with parenthetical lists, which is slightly heavy, but every clause carries information and 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?

For a no-parameter, read-only tool with an output schema and full annotation coverage, the description supplies everything the remaining burden requires: auth requirement, content scope, resource equivalence, and how the returned ids are consumed downstream.

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?

Zero parameters, so the baseline is 4. The description still earns its place by explaining that the returned entity_id and commission_id values plug into list_regulations and list_bills, which is useful cross-tool semantics rather than parameter detail.

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 the specific resource (the signed-in user's identity in Dapper) and enumerates its fields: email, default country, interest tags, watched entities and commissions. It also distinguishes itself from lookup siblings by explaining that it returns the ids those other tools accept.

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 two concrete situations: grounding a personal briefing, and explaining why a call was scoped a certain way. It doesn't explicitly name a sibling it should be preferred over (e.g. list_my_followed_bills or update_my_interests), so the routing guidance is clear but not exhaustive.

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/idempotent annotations: it discloses that seats count only ACTIVE mandates, that has_majority is null (not false) when chamber totals are unknown, and that member sampling is bounded with members_truncated signaling more. These are non-obvious semantics an agent could not infer from 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 profile contents, then the prerequisite resolution step, then the count semantics. Dense but every sentence carries information; the seat-counting and null-majority caveats are well placed.

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 an output schema present and annotations covering the safety profile, the description fills the remaining gaps: resolution prerequisite, active-mandate seat counting, null-majority behavior, and truncation signaling. 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?

Schema coverage is 100%, so parameters are already documented, but the description adds semantic depth: the id-resolution rationale and the meaning of member_limit sampling with members_truncated and list_actors paging. This exceeds the baseline 3 by clarifying behavior rather than just restating 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 profile for one political party' with concrete contents (seats per chamber, sample legislators, recent bills). Distinguishes itself from list_parties, which is named as the name-resolution sibling.

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 instructs the agent to resolve a name to party_id via list_parties(country_code=...) first, and explains why (party names repeat across coalitions and eras). It also names list_actors(party_id=...) as the way to page all members rather than the sample.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds substantial context: the 30-day lookback, daily breakdown, client name/tier, and the hard scope restriction to the calling key. These details tell the agent what data will be returned and what access is impossible beyond the safety hints.

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 front-loads what is returned, then states the scope restriction, then gives use cases in compact sentences. Every sentence adds decision-relevant information with no filler.

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

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

With an output schema, no input parameters, and rich annotations, the description supplies the remaining context an agent needs: time window, scope, return dimensions, and typical use. No important calling condition appears to be 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?

The input schema has zero parameters and is an empty object, so there are no parameter semantics to document. The baseline for zero-parameter tools is 4, and the description appropriately avoids inventing parameters.

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

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

The description names a specific verb and resource: usage of the calling API key over the last 30 days, including request count, error count, latency, client name, and tier. It also explicitly rules out legislative data, which separates it from the many legislative list_* and get_* siblings.

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 concrete reasons to call it, such as checking quota proximity and explaining error bursts, and it states a clear boundary: there is no way to read another client's usage. It also steers away from legislative-data tools, though it does not name a specific sibling alternative for quota-related questions.

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, and the description adds substantial behavior beyond them: `id` overrides every other filter and returns a bundled profile with capped votes and bills, `meta.total` counts all matches while `meta.has_more`/`next_cursor` drive paging, the `q` keyword fallback is a single relevance-ranked page of at most 20 rows, and executive-branch coverage is heavily skewed to Brazil. These are exactly the operational caveats an agent cannot infer from structured fields.

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 and clearly sectioned with bold headers ('No `id`', 'Counting seats', 'With `id`'), and every section maps to a real invocation pattern. It loses a point for density that borders on redundancy, e.g. the chamber token-matching vocabulary is restated in both the general and counting guidance.

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 the full decision surface for a 10-parameter tool with 0 required params: default behavior, filter combinations, pagination semantics, override behavior of `id`, coverage limitations, and where to go for data this tool truncates. An output schema exists, yet the description still correctly flags the shape of the bundled profile response.

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 schema already carries per-parameter meaning and the baseline is 3. The description adds genuine semantic value on top: how to combine `party_id` with `chamber` and read `meta.total` for seat counts, the majority-question recipe (rerun the same count without `party_id`), and why `has_mandate` should be left unset for executive queries.

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 set (list, search, fetch one by id) and a specific resource (political actors: congresistas, ministros, legisladores, funcionarios), explicitly framed as a single tool that consolidates three prior calls. An agent can distinguish it from list_parties, list_votes, or list_bills immediately.

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 branches: no `id` for rosters, `q` to resolve a name to an id, `branch="executive"` for ministers, `commission_id` for commission membership, `party_id`+`chamber`+`meta.total` for seat counts. It also names the alternatives and their thresholds (use list_votes/list_bills/list_interventions/list_actor_tweets for more than 10 votes / 5 bills), and warns against paginating a roster to tally seats yourself.

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, and the description adds genuinely new context: ordering (newest first), absence of any sentiment or analysis field, and a prompt-injection warning about untrusted third-party content. What is missing is any note on empty results or tweet retention/refresh behavior.

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 first two sentences are tight and front-loaded, but the 'Data sources' paragraph is about actor records, not tweets, and consumes over half the text with off-topic provenance caveats. That material belongs on list_actors, not here, and dilutes the signal.

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?

An output schema exists, so return-shape explanation isn't needed, and pagination is covered by the cursor parameter. However, for a simple read tool the description spends its length on irrelevant actor sourcing while leaving tweet-specific behavior (volume, currency, whether retweets are included) unstated.

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 id, limit (1-500), and cursor are already fully documented. The description reinforces 'newest first' but adds no syntax or semantics beyond what the schema states — the 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?

The opening sentence gives a specific verb+resource ('paginated tweets linked to this actor, newest first') and the second names the payload shape (raw text plus engagement counts). No sibling tool lists tweets, so no confusion arises, though the purpose statement is then buried under unrelated actor-record 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?

It implies when to use it (raw signal retrieval instead of analysis) and the third-party-content caveat sets reporting expectations, but there is no explicit statement of when to prefer this over, say, list_transcripts or search, nor any prerequisites beyond the id resolution already in the schema.

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 past the annotations (readOnly/idempotent/non-destructive), which it does not contradict. It discloses non-obvious behavior: `meta.total` is null with `q` and on later pages, semantic hits carry `rerank` and negative rerank means rejected, `relevance` is raw cosine and does not discriminate, caps of 200 tramitaciones / 20 votes / 10 interventions, country_code omission falling back to the OAuth default rather than 'all', and author-coverage gaps (91% CO/PE vs 28% BR/CL/DO, 0% VE) so an empty `authors` isn't misread.

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 justified by 13 parameters and three distinct modes, and it is strongly front-loaded with bold section headers that let an agent jump to the relevant branch. Some passages duplicate the schema descriptions nearly verbatim (q/code guidance, cursor rules), which is the main slack in an otherwise dense, well-organized text.

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 13-parameter, three-mode, cross-country tool it covers what an agent needs to call correctly: mode selection, filter interactions, pagination, count semantics, empty-result interpretation, and where to go when caps are exceeded. Return-value explanations are a bonus rather than a gap, since an output schema exists and the annotations already carry the safety profile.

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 per-parameter descriptions are already detailed, so much of the prose (code vs q, party_id semantics, cursor handling) restates structured data. It still adds practical semantics the schema does not carry as crisply — e.g. that a bill number in `q` 'actively breaks the search', that `min_similarity` is a coarse filter while `min_rerank` is what discriminates, and the counting recipe using `since`/`until` with `limit=1`.

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 gives a specific verb set and resource ('list, search, or fetch one by id') plus the data provenance ('official docket system, refreshed daily'). It then disambiguates its three modes with headers ('No `id`', 'Only know the topic?', 'With `id`'), so an agent can pick the branch without opening the schema, and it explicitly names the siblings it supersedes (get_bill + list_bill_updates + list_bill_votes + list_bill_interventions).

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 rules for every access pattern: topic → `q`, known number → `code` (not `q`), one bill → `id`, one legislator → `actor_id`, more than the caps → list_bill_updates/list_votes/list_interventions. It also states exclusions (actor_id ignores commission_id/q/since/until) and the party_id discovery path via list_parties.

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 read-only/idempotent safety, so the description spends its space on non-obvious behavior: default 7-day window in feed mode, `since`/`until` filtering on created_at as 'a close but not exact proxy' for the real tramitación date, and the country fallback where omitting is not the same as 'all' and reports `meta.country_scope`. These are failure modes an agent would otherwise hit blindly.

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 a one-sentence mode summary before the bolded per-mode blocks, which is exactly the right structure. It is on the long side and restates some schema parameter text (e.g. since/until proxying), so a little could be trimmed without losing meaning.

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 an output schema present, the description needn't describe return shapes, and it covers everything else an agent needs: both modes, filter interactions, defaults, paging caveats, and the country-scope fallback. Nothing material is left to inference.

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 schema already documents each parameter; the description's added value is cross-parameter semantics — which filters each mode ignores, the default window, and the comma-separated/all/omit distinction for country_code. It slightly overlaps the schema text rather than adding wholly new per-parameter detail, so 4 rather than 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?

Opens with a specific verb+resource ('Legislative updates (tramitaciones) for a bill') and immediately states the dual-mode nature keyed on `bill_id`. It also distinguishes itself from sibling `list_bills`, noting that tool already returns up to 200 of these inline, so an agent can pick correctly 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?

Explicit when-to-use for both modes: bill_id mode for one bill's ordered sequence, feed mode for 'what moved yesterday/this week' or 'what did commission X decide this week'. It goes further and names the alternative (`list_bills`) plus the exact condition for preferring it (need >200 or independent paging).

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, so safety is covered. The description adds value beyond them: results are limited to *active* commissions, and the data-sources note warns that returned ids are internal lookup values, not citable documents — a real behavioral constraint an agent would otherwise get wrong.

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 primary use are front-loaded in the first two sentences; examples are inline rather than listified. The closing data-sources paragraph is longer than strictly needed but carries the non-citability caveat that would otherwise be lost.

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?

Output schema exists, so return values need no explanation, and the description covers scope, filtering, and the intended downstream use. Nothing essential is missing for a simple lookup tool; only minor edge cases (pagination, empty results) are 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 100%, so the baseline is 3. The description still adds the default when country_code is omitted ('all accessible countries') and restates the comma-separated format with examples plus acronym matching, which sharpens how `q` behaves beyond the schema's wording.

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 active congressional commissions') and immediately ties it to a downstream consumer ('discover commission_id values to pass to list_bills'). That routing sentence separates it cleanly from sibling list_* lookup 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 names the primary use case and the sibling it feeds. It also gives the fallback behavior ('omit for all accessible countries') and concrete filter examples, so the agent knows both when to call it and how to call it with no configuration.

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 safety needs no restating. The description usefully signals that the board set is small and volatile ('Five boards today'), but never explains what the country_id/country_code filters do to the result set, which is the main behavioral unknown for a tool that otherwise looks Colombia-only.

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 relationship to list_committee_minutes are front-loaded in the first clause, and the enumeration is real payload rather than filler. Embedding live counts in prose risks staleness, but it is compact and each element earns its space.

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?

An output schema exists, so return shape need not be described, and the annotation set covers the safety profile. The only material omission is the effect of the country filters, which is left entirely to 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 description coverage is 100% and both optional params are documented in-schema (including the deprecated alias warning), so the baseline is 3. The description adds nothing about the params, and notably never says whether country filtering changes or merely narrows the board list.

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 (INVIMA's specialized committee boards) and what the response yields (exact names plus per-board minute counts). It is immediately distinguishable from list_committee_minutes, which consumes the names this tool supplies.

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 frames the use case: call this first so you don't have to guess the spelling for `board=` in list_committee_minutes. That is a concrete when-to-use plus a named downstream consumer, which is exactly the routing 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 already declare read-only, idempotent, non-destructive behavior, so the description adds scope context instead: Colombia-only coverage, exact corpus size (5,483 minutes / 2,858 cases), the session date range, and the fact that each minute is ~210 chunks and 87% of Colombia's index. It does not cover result ordering or pagination behavior, but the essentials are there.

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?

Roughly four sentences, front-loaded with what a record contains before the exclusion/exclusivity point. The corpus statistics sentence is slightly heavy but earns its place by justifying the separate endpoint. No filler.

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

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

With 11 optional parameters, a full output schema, and rich annotations, the description supplies the missing pieces: geographic scope, corpus scale, and the relationship to list_regulations. Ordering and pagination semantics are left implicit, a minor gap for a list tool that supports cursors.

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 every parameter (q, board, decision, dates, cursor, case_number, requires_label_update, deprecated country_id) is documented in the schema itself, so this is the baseline case. The description adds no filter syntax or combination guidance beyond what the schema already carries.

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 (committee minutes) and enumerates exactly what each record contains — board, minute, case (applicant, composition, dosage form), decision, and label-update flag. It explicitly distinguishes itself from the sibling list_regulations, so an agent can classify it 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?

It names the alternative tool (list_regulations) and states why these records are not there by default, which is precisely the decision an agent faces. It also routes follow-up work: 'Use `id` for the full concept and background text,' pointing at the per-record detail tool.

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 the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses the payload limitation (no body/summary, only title/dates/external_link, follow the link for substance), the semantic-then-keyword fallback with a relevance floor that drops filler rather than padding results, and that omitting `country_code` is not the same as 'all' and shows up in `meta.country_scope`. Those are non-obvious behaviors an agent would otherwise discover by surprise.

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?

Strong front-loading with the mode split bolded before any filter detail, and the two-mode structure mirrors how an agent will actually branch. Some content is doubled up with the schema (the `list_entities` resolution hint and the semantic-threshold explanation appear in both), which keeps it short of maximally tight.

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 14-parameter tool this is adequately covered: annotations give the safety profile, an output schema exists so return shape needn't be spelled out, yet the description still flags the one return detail that changes behavior — the missing body field and the external_link workaround. Nothing needed to call it correctly is absent.

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 per-parameter meaning is already carried; the description's added value is combinatorial — pairing `order_by="end_date"` with `status="open"` for 'what closes next', pairing `status` with `closing_before` for a rolling window, and the rule that a cursor only continues the order and filters it came from. It repeats some schema content (min_similarity, entity_id resolution), so it lands above baseline but not a full parameter-reference replacement.

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?

Opens with the specific resource plus verb set — 'list, search, or fetch one by id, in a single tool' — and immediately separates the two modes (no `id` = paginated list, with `id` = full detail). It also names the boundary case that matters versus siblings: `list_entities` is where agency names get resolved, not here.

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 for the real questions agents ask: 'status="open" for consultations still accepting comments', '¿qué consultas públicas abrió <agencia>?' → list_entities first, and 'for closing in the next N days pass status=open plus closing_before=<today+N>'. It even states the exit condition for search — 'narrow `q` instead of paging' — rather than leaving it 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds genuinely non-obvious semantics: thin-ingestion domains (votes, interventions) are omitted from both `domains` and `domains_health` while their endpoints still serve data; `domains` means 'ever had data', not 'current'; and `domains_health` is guaranteed to agree with get_health/get_country_health. These are exactly the behavioral caveats an agent cannot infer on its own.

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 tight paragraphs: purpose first, then a usage directive, then field semantics. The final clause ('computed the exact same way as get_health/get_country_health — the two are guaranteed to agree') states the same fact twice, a small redundancy in an otherwise waste-free definition.

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?

An output schema exists, so return shape needn't be explained, but the description still names the two key fields (`domains`, `domains_health`) and their differing meaning — the exact distinction an agent needs before deciding whether to trust the coverage map. Complete for a zero-parameter lookup 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?

The tool takes zero parameters and the description correctly spends no space on argument semantics. Baseline is 4 for a no-argument tool.

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

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

States a specific resource and scope: a reference catalog of the 12 LATAM countries plus per-country domain coverage (regulations, consultations, bills, actors, schedules, news, transcripts). This clearly distinguishes it from the sibling data-fetching tools like list_regulations or get_country_health, which return actual records rather than a coverage map.

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 'Call this first when unsure whether a country or domain is covered before querying it' — a concrete when-to-use rule. It also names the alternative for a related question (use `domains_health` for freshness) and ties that signal to get_health/get_country_health, leaving nothing 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 carry readOnly/idempotent/non-destructive/openWorld=false, so the description correctly focuses elsewhere: data provenance (official registries, gazette attributions, congress rosters) and the important caveat that these are internal lookup values, not citable documents. It does not discuss pagination or the 50-match cap beyond what the schema states.

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 use case are front-loaded, and each paragraph has a job. The closing data-sources note is denser than strictly necessary but carries a real citation-hygiene warning rather than 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 an output schema present, the description needn't explain return shape, and it covers the remaining gaps: entity types, id semantics, query strategy, country scoping, and citation caveats. An agent could call this correctly from the definition alone.

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 3 is the baseline; the description earns more by adding behavior the schema omits — that `country_code` comma-separated and omitting it means all accessible countries — and by illustrating multi-word memory matching that implies broader matching than a plain substring.

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?

Opens with a specific verb+resource ('Returns the full list of government entities') and enumerates the entity kinds covered. It then states the purpose that distinguishes it from list_top_entities and list_regulations: discovering entity_id values.

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 names the downstream tool ('Primary use: discover `entity_id` values to pass to `list_regulations`'), telling the agent both when to call it and what to do with the result. It also explains the query-strategy choice for `q` (name vs acronym vs remembered-name words).

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 closed-world, so the safety profile is covered. The description adds real substance beyond that: coverage is Colombian and sectoral only, pieces are sourced and dated when they exist, and the list returns summaries rather than bodies. Return field details are left to the output 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?

Front-loads what the resource is, then usage, then the coverage caveat, then the follow-up path in four tight sentences. Every sentence carries information, though the examples and the quorum/majorities enumeration are slightly heavier than needed.

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 an output schema and full annotation coverage in place, the description supplies exactly the missing pieces: the domain boundary of the content, the fact that the list is summary-only, and the id-based path to the full body. Nothing an agent needs to call this correctly is absent.

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%, with q, limit, country_id (marked deprecated) and country_code each documented in the schema itself. The description adds no parameter-level detail — the mention of 'summary' and 'id' is about returned data, not inputs — 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?

States a specific verb and resource ('Dapper's own curated explainers ... written by the editorial team') with concrete examples of the content type. It also distinguishes itself from the sibling get_explainer by noting that the list carries only the summary and the body requires fetching by id.

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 ('For definition questions') and an explicit exclusion ('legislative procedure is not covered here: quorum, majorities and deadlines have no piece'), which steers an agent away from a dead end. It stops short of naming the alternative tool (get_legislative_process) that should be used instead, leaving that inference to the agent.

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 read-only, idempotent and closed-world behavior, and the description adds something annotations cannot: data-quality disclosure that coverage varies sharply by domain and that regulations are barely tagged. It does not address pagination or result size, which would matter for a catalog query.

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 definition, then caveats, then search syntax in a logical order; every clause carries signal. The nested parentheses around the list_news pointer make it slightly denser than necessary, but nothing is 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?

Output schema and annotations together remove the need to describe return shape or safety, and the description supplies the domain-coverage caveat an agent needs before trusting the tags. The one gap is the unresolved tension between 'one global list' and the still-present country_id/country_code parameters.

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 all three parameters are already documented; the description adds only a worked example for `q`. It leaves ambiguity around the country parameters: the description declares the list 'Not country-scoped — one global list' while the schema still exposes country_id and country_code, and it never clarifies whether passing country_code does anything.

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 (catalog of topic tags, 'Intereses') and ties it to two concrete roles: the topics users pick in the portal and the categories content is tagged with. That framing distinguishes it from update_my_interests (mutation) and from list_news/list_regulations, whose interest_tag_id filter it explicitly points at.

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 actionable when-to-use context: the tags are well-populated for news and nearly empty for regulations/bills, so the agent is routed to list_news's interest_tag_id filter for the domain where the data is real. It also states the list is not country-scoped and shows how to search with `q=Salud`.

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 the safety profile (readOnly, idempotent, non-destructive), and the description adds operational behavior that annotations cannot express: list rows intentionally omit the `content` transcript to keep pages light, `id` returns full detail, and omitting `country_code` falls back to the caller's default country rather than meaning 'all'. The 462-row/Colombia-Perú coverage caveat is exactly the kind of non-obvious trait that prevents false 'no results' conclusions.

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 front-loaded with the purpose and the coverage warning, then cleanly segmented into 'No id' and 'With id' behavior using bold headers — easy to scan. It is somewhat long and repeats the transcript-omission point already present in the `id` schema description, so a sentence or two 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?

For an 8-parameter, all-optional, dual-mode tool this is thorough: it covers mode selection, filter combination, pagination implications, country scoping defaults, and known data gaps. With an output schema present and rich annotations, nothing an agent needs in order to call it correctly is 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?

Schema coverage is 100% and the parameter descriptions already carry pagination cursor mechanics and country_code formats, so the baseline would be 3. The description earns above baseline by explaining cross-parameter interaction the schema cannot: `id` ignores all other filters, `bill_id` and `actor_id` are combinable, and `since`/`until` filter on the intervention's own date rather than a linked bill's date.

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 resource (interventions/discursos) and explicitly splits the tool into list, filter, and fetch-by-id modes, which is the key distinction an agent needs. It also states which legacy/sibling operations it absorbs (get_intervention, list_bill_interventions, list_actor_interventions), so the agent knows it doesn't need a separate detail call. The only blemish is the slightly self-referential 'Replaces list_interventions + ...' note for a tool literally named list_interventions, but the functional purpose remains unambiguous.

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 branching rules: use `id` for full transcript vs. omit it for a list, `bill_id`/`actor_id` are freely combinable to scope to a bill or legislator, and neither gives a cross-country list. It also says `id` overrides every other filter, and warns that empty results are usually a dataset coverage gap rather than a bad query — a concrete corrective instruction.

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?

Matches annotations (readOnlyHint=true) with 'This only reads', so there is no contradiction. Beyond that it discloses genuinely useful traits: the deliberate 404 masking of not-found vs another company's private listening, the ready/processing/failed timing envelope, and the fact that a finished report's generated title replaces the requested one. However, the metadata fields it references (`is_owner`, `has_metrics`, `meta.country_scope`, `meta.mode`) are described only in passing rather than explained, which leaves some behavioral gaps.

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 and well-sectioned with bold mode headers, so an agent can scan the default path versus the id path. It is longer than strictly necessary — the closing sentence about the generated title is useful but buried, and a few clauses (e.g. the quota aside) serve the sibling tool more than this one.

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-param, zero-required read tool with a full output schema and complete annotations, this covers everything the agent needs: mode selection, filter semantics, pagination behavior, status meaning, and the privacy-driven 404. Return-value detail is rightly deferred to the output 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 100% and the schema itself already documents filters, cursor, and limits thoroughly, so the baseline is 3. The description adds real value on top: it warns that omitting `country_code` is NOT 'all' under OAuth and points to `meta.country_scope`, and it cross-references `has_metrics` and `is_owner` as signals. It restates rather than extends the `id`-overrides-filters rule, which 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?

Opens with a specific verb+resource ('Social listening (PolifonÍA) — what was said on X and Google Trends about a topic') and immediately states the dual mode: list all, or fetch one by id. The scoping ('every public one for the countries they access, plus their own company's private ones') is precise enough to separate it from list_news, list_entities, and every other list_* sibling.

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 branches on `id`: without it you get a filtered list, with it you get the report and metrics and 'every other filter is ignored'. It also routes the agent to sibling tools for the write path ('check get_listening_quota, then create_listening') and tells the agent to read `status` before trusting an empty report.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds critical context beyond annotations: it requires a signed-in session, an API key without a client_email yields no watchlist, and a follow made via follow_bill may take a few seconds to appear. These details materially affect correct invocation.

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 contrasts with alternatives immediately. Every sentence earns its place: it covers purpose, output shape, mutation consistency, auth requirements, and error behavior without redundancy or 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?

Given that an output schema exists, the description still helpfully summarizes return fields (title, authors, latest_state, dapper_url, followed_at, notify, meta.total) so an agent can plan without opening the output schema. It also covers auth prerequisites and eventual consistency, leaving no critical gaps for a read-only list 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%, so the limit and cursor parameters are already fully documented with constraints, defaults, and pagination behavior. The description does not add further meaning about these parameters beyond the schema, so the baseline score of 3 is appropriate.

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: 'The bills the logged-in user follows in the Dapper platform, newest follow first.' It explicitly distinguishes the tool from search and from list_bills by noting 'This is their own watchlist, not a search' and that rows match list_bills' shape. An agent can immediately tell what this tool returns and how it differs from siblings.

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?

Provides explicit when-to-use guidance through sample user questions ('¿qué proyectos estoy siguiendo?', '¿alguno de los que sigo se movió esta semana?') and a purpose statement ('to ground a briefing in what this person already cares about'). It also names the mutation alternatives follow_bill and unfollow_bill, making the read-only role 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?

Annotations already establish read-only, idempotent, non-destructive, but the description adds substantial behavior the annotations cannot convey: OAuth-vs-API-key degradation of the no-filter call, the widening cascade on the briefing path and the `widened` field that must be reported honestly, the `NO_INTERESTS` structured negative, row-size warning with a hard 10-item cap for `content`, and a prompt-injection warning about third-party text. That is well beyond the annotation bar.

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?

Bold mode headers make it skimmable and the highest-stakes guidance (digest size, injection warning, primary-source routing) is front-loaded. It is long, however, and several points — the 10-item content cap, the country_code omission semantics, the cursor/q paging rule — are restated almost verbatim from the schema descriptions.

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 an 11-parameter tool with four operating modes, this covers what an agent needs to call it correctly: which mode a given filter combination triggers, what the negative results mean, and how to size requests without exhausting context. Return-value shape is partly handled by the output schema and partly called out by name (`widened`, `meta.country_scope`, `meta.next_cursor`).

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, and the description earns an extra point by explaining cross-parameter interactions the schema cannot: `id` voids all other filters, `interest_tag_id` is ignored when `q` finds a semantic hit, and omitting `country_code` falls back to the OAuth default (visible in `meta.country_scope`). Some of this repeats schema text (the 'omit is not all' note, the content cap), which keeps it below 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?

The description names the resource (political/regulatory news) and enumerates the four distinct operations — list, search, fetch by id, personalized briefing — in the first sentence. It explicitly differentiates from the closest siblings (bills/regulations/schedules) by scope ('news coverage of it, not the primary-source record') and from general news search ('narrower than general news search').

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 routing: use bills/regulations/schedules when you need the primary record; resolve interest_tag_id via list_interest_tags(q=...) first; pass content=true only after you know which item you want, or fetch by id; call again with an explicit interest_tag_id on a NO_INTERESTS result rather than concluding the account has no interests. Exclusions and alternatives are both present.

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 the read-only, idempotent, non-destructive, closed-world profile, yet the description adds real context: result size for an unfiltered query and the fact that these are internal lookup values that should not be cited as sources. It doesn't discuss pagination or ordering, which keeps 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 with the core behavior and filtering advice, with examples embedded inline. The bolded data-sources paragraph is longer than strictly necessary for selection, though it does carry the citability rule, so it still 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 annotations covering safety, an output schema covering return values, and full parameter coverage, the description supplies exactly the missing pieces: scope, filter strategy, result volume, and citation caveats. Nothing needed to invoke it correctly is absent.

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's examples for q and country_code largely restate the schema, and it never mentions the deprecated country_id alias, so it adds only the marginal behavioral note that omitting q returns the full catalogue.

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 all political parties") plus the scoping dimension ("for the requested countries"). It also situates the data relative to siblings by noting party names appear in actor and vote records, so an agent can tell this apart from get_party or list_actors.

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 operating guidance: omit country_code for all accessible countries, use q for name/acronym matching, and "resolve the name here rather than reading the list and guessing." The 91-row Colombia example concretely motivates the filter. It stops short of naming when to prefer the singular get_party sibling.

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/idempotent/destructive=false and openWorld=false, so the safety profile is covered and the description does not need to restate it. The description does add real behavioral context beyond annotations, notably the gazette-feed caveat, refresh cadence, citation rules (cite rerank not relevance; cite display_title; title stays as printed), and pagination quirks. It stops short of describing rate limits or auth requirements, so a 3 is appropriate rather than a 4.

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 and every section maps to a real decision, but it is long and heavily formatted for a tool description, with duplicated guidance between `q`, `number`, `min_rerank` and `min_similarity` in both prose and schema. It is dense rather than wasteful, but it is not tightly sized for its purpose.

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 an output schema present and rich annotations, the description still covers the hard parts an agent must know: mode selection, number vs topic search, citation-score selection, committee-minute exclusion rationale, and the near-miss behavior. Nothing material for correct invocation 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, and much of the description duplicates schema text (e.g. number matching, min_similarity vs min_rerank). It nonetheless adds cross-parameter semantics the schema cannot express — that setting `id` ignores every other filter, that omitting country_code is not the same as 'all', and that cursor paging with `q` continues only the keyword branch — which pushes it above 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?

The opening line names a specific resource (regulations/normativas) and explicitly enumerates the three modes (list, search, fetch by id), which is exactly the distinction an agent needs. It also qualifies the data source (official gazettes, refreshed daily) and contrasts itself with a compendium of law in force, so the scope is unambiguous against siblings like list_committee_minutes or get_document_text.

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

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

The description routes every common case: no id for list mode, id for full detail, `number` when the norm number is known, `q` when only the topic is known, and it names list_regulation_types / list_entities for ID discovery. It also gives explicit exclusions and alternatives — e.g. use list_committee_minutes for INVIMA board minutes — which is the strongest form of when/when-not 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 cover read-only, idempotent, closed-world behavior, so the description's job is extra context — and it delivers: result ordering (most-used first, or alphabetical in global mode), the `regulation_count` field, and the cross-country id collision pitfall that would otherwise cause wrong results. The data-source paragraph adds provenance but is bulkier than it needs to be for invocation decisions.

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 operational content is front-loaded and tight — mode selection, the id-scoping warning, then the `q` behavior. The trailing data-sources sentence naming gazettes and agency portals is long and largely irrelevant to choosing or calling the tool, diluting an otherwise efficient description.

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 two optional params, an output schema covering return shape, and annotations covering the safety profile, the description fills all remaining gaps: which mode to pick, ordering, the id-collision hazard, and what `regulation_count` means. 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 coverage is 100%, so baseline is 3; the description earns above that by specifying that `q` is accent- and case-insensitive and that `country_code` takes exactly one country and scopes ids and adds usage counts. That is real semantic detail beyond the schema's bare 'Filter by type name' and 'One country'.

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 first sentence states the exact resource (regulation type codes: decretos, resoluciones, circulares) and its role as the source of `rtype_id` for `list_regulations`. That relational framing lets an agent place it against the sibling list tools immediately.

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 splits the two modes explicitly: with `country_code` you get only that country's types from the last two years, most-used first; without it you get the global alphabetical catalog. It also routes the agent to use the scoped list rather than global ids, because names repeat across countries — a concrete when/when-not distinction.

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 read-only, idempotent, non-destructive and closed-world, so the bar is lower; the description still adds real context on provenance and freshness (official calendars, refreshed every 1-2 hours on session days), country-scope fallback vs 'all', and the single-page relevance fallback for `q`. It stops short of describing auth/rate-limit constraints or the detail payload shape, though the output schema covers the latter.

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 split into bold-labeled 'No id' / 'With id' modes, which is easy to scan. It is on the long side and repeats some schema text (e.g. the week-ahead example, cursor guidance), so a point comes off for redundancy rather than for structure.

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 9-parameter, dual-mode listing tool with an output schema, the description covers everything needed to call it correctly: mode selection, filtering, ordering, pagination, scope defaults and the empty-result interpretation. Nothing an agent needs 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?

With 100% schema description coverage the baseline is 3, but the prose adds cross-parameter semantics the schema states only piecemeal: that a cursor only continues the order it came from, that `id` overrides all other filters, and that omitting country_code differs from 'all' via meta.country_scope. This is meaning beyond a per-parameter restatement.

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?

Opens with a specific verb+resource ('Legislative agenda (sesiones, audiencias, debates) — list, or fetch one by id'), and explicitly resolves the dual-mode ambiguity by explaining that `id` switches to detail. An agent can distinguish it from list_bills, list_commissions and list_committee_minutes 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?

Gives explicit when-to-use branches: omit `id` for a paginated list, pass `id` for full detail, use order_by='event_date' with since=today for the week ahead, and points at list_commissions(country_code=...) to discover commission IDs. It also states when-not behavior ('ignores every other filter') and the keyword-only limitation of `q`.

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 the safety profile (readOnly, idempotent, non-destructive), so the description rightly spends its words elsewhere: distinct-bill counting, dedupe of repeated authors, and a prominent data-coverage caveat (~91% CO/PE vs ~28% BR/CL/DO, none VE). That caveat materially changes how an agent should present results, which is exactly the value-add expected when annotations carry the rest.

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 ranking definition, then parameter behavior, then the warning — a sensible order with no wasted sentences. It is on the long side and restates one or two schema facts, but every paragraph carries distinct information.

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?

All seven optional parameters are addressed at the level an agent needs, the counting and window semantics are settled, and the output schema already documents the return shape. The coverage warning closes the one gap that could otherwise cause a misleading answer.

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 real meaning by tying since/until to the bill's *filing* date and clarifying that omitting country_code means every accessible country. Some content (co_author_of exclusion, party ID discovery) duplicates the schema text rather than extending it, keeping this short of 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 precise verb and ranking semantic ('legislators ranked by how many bills they filed in a window') and contrasts it with the naive alternative of paging a whole docket and tallying client-side, which separates it from list_bills and list_top_entities. An agent knows exactly what this returns before 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?

Explicitly names the question it answers, tells the agent when to switch modes via `co_author_of=<actor_id>`, and routes ID discovery to list_parties for parties. It also gives an exclusion rule (omit country_code for all accessible countries), which is real selection guidance rather than filler.

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 behavior, so the safety profile is free. The description adds genuinely non-obvious traits: results are aggregated and ranked descending rather than raw rows, domain coverage is structurally limited, and returned entities are internal lookup values that must not be cited directly — the underlying regulation/bill/actor record should be cited instead. Return-shape details are omitted, but an output schema exists to cover that.

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 front-loaded — the aggregation purpose and the 'instead of paging' rationale come first, then parameters, then exclusions, then provenance. The data-sources paragraph is longer than strictly necessary but earns its place by establishing that entities are non-citable, which prevents a downstream citation error.

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 aggregation tool with a full schema and an output schema, nothing actionable is missing: what is counted, how it is ranked, the supported domain universe, the window and country filters, and a citation caveat are all present. The explicit list of unsupported domains removes the main failure mode for 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 coverage is 100%, so baseline is 3. The description still adds operational meaning beyond the schema: domain is required and selects which activity is counted, since/until bound the counting window (with a 'last 10 days' example), and country_code is comma-separated with an omission rule. Only country_id's deprecated status is left entirely to 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 states a specific verb and resource — an aggregated, descending-ranked count of regulations/consultations per issuing entity — and explicitly contrasts it with paging raw rows client-side, which distinguishes it from siblings like list_regulations and list_entities. An agent can tell exactly what this returns 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?

It names the question patterns this answers ('most active entities', 'who issued the most regulations') and gives an explicit negative case: bills/news/schedules/votes/actors/interventions/transcripts are not supported and still require paging plus manual synthesis. It also says to omit country_code for all accessible countries, so both when-to-use and when-not-to-use are covered.

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 read-only, idempotent, non-destructive behavior. The description adds important behavioral context beyond annotations: results are country-dependent, include counts, and an invalid guessed origin produces a misleading empty result.

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 followed by the exact usage condition. The country-specific examples are directly relevant and earn their 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?

For a one-parameter discovery tool with rich annotations and an output schema, this is complete. It covers purpose, when to call it, sibling relationship, and the key empty-result pitfall; return-format details are appropriately left to the output 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 100% and the sole country_code parameter is already documented as comma-separated. The description reinforces country-scoped behavior and gives country-specific vocabulary examples, but does not add syntax or default behavior 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 first sentence names the exact resource (origin values), scope (per country), and payload (transcript counts). It also distinguishes this discovery tool from list_transcripts by explicitly saying it is used to discover valid origin filters.

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 tells the agent to call this before list_transcripts to discover valid origin filters. It also explains why guessing fails: country-specific vocabulary means a bad value returns an empty list that looks like no sessions.

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 cover the safety profile (readOnly, idempotent), but the description adds substantially more: a prompt-injection warning that the text is third-party content, the `text_kind` trap where the body is Dapper's own Resumen Legislativo rather than verbatim speech (and must be attributed to Dapper), the ~93% `external_link` PDF coverage, and the 20-item cap on `content=true`.

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 definition, then bolded mode headers, then the quoting caveat — good scannable structure for an 11-parameter tool. It loses a point because several sentences duplicate the schema descriptions near-verbatim (the `content=true` rationale, the cursor rules), which is redundant payload for the agent.

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?

An output schema exists and annotations cover safety, so the description only needs the judgment calls — and it supplies them: fallback to keyword match with `meta.relaxed_query`, relevance pages being a single non-pageable page of 20, `min_rerank` as the discriminating knob versus `min_similarity` as a coarse filter. 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 and the schema already carries the per-parameter detail. The description still earns credit for cross-parameter guidance the schema spreads out: `origin` vs `q` as competing filters, omitting `country_code` not equalling 'all' under OAuth, and the `content` cap that overrides `limit`. Much of this is echoed verbatim from the schema, so it is reinforcement rather than new semantics.

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?

Opens with a specific resource and its scope (transcribed sessions/broadcasts, with real-world examples), and enumerates the three operations: list, search, fetch-by-id. It also distinguishes its two modes (no `id` = paginated list; `id` = full detail), so an agent knows exactly which shape of call it is making without consulting siblings.

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 rules: use `id` for detail, use `content=true` to avoid N+1 lookups, use `origin` rather than putting the session kind in `q` ('mañaneras de esta semana' is a filter, not a topic), and defer to `list_transcript_origins()` for the catalogue. The 'summarize what was discussed about X this week' worked example ties parameters to an intent.

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, so the safety profile is covered. The description still adds genuine domain context: most votes have no linked bill, project_information is the text context for those, recorded_at differs from the sparsely populated vote_date, and omitting country_code falls back to the user's default country (surfaced in meta.country_scope). However, it does not touch on result ordering or the volume/rate characteristics of a cross-country feed, so it is strong context rather than full behavioral disclosure.

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 the tool is and the sibling it supersedes, then parameter guidance in descending order of importance. It is dense and mostly earns its length, but the recorded_at/vote_date caveat and the commission_id warning are duplicated verbatim in the schema, adding some 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?

With 8 optional parameters, an output schema, and full annotation coverage, the description supplies everything the structured fields cannot: which filters to combine for which question type, the semantic gap between recorded_at and vote_date, the default-country fallback, and when a different sibling tool is the better answer. Nothing needed 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?

Schema coverage is 100%, so a baseline 3 applies, but the description adds real meaning the schema does not: that bill_id and actor_id are freely combinable, that country_code accepts comma-separated or list form with 'all' being distinct from omission, and the practical consequence of commission_id excluding ~79.5% of votes. Some caveats (recorded_at vs vote_date, the commission_id warning) are restated from the schema, keeping it below 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?

Opens with a specific verb+resource ('Voting records (roll-calls)') and states provenance ('sourced directly from official chamber publications'). It also distinguishes itself from its predecessors by naming the three merged tools and explaining the scoping parameters that replace them, so an agent can tell what this returns 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?

Gives explicit routing: pass bill_id and/or actor_id (freely combinable) to scope, or neither for a raw feed; use since/until for 'votes this week'; use commission_id only for bill-linked votes. It names a concrete alternative with the condition that selects it ('for what did commission X decide this week prefer list_bill_updates(commission_id=...), which covers tramitaciones too').

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 the safety profile (read-only, idempotent), and the description adds substantial behavior beyond them: hybrid→keyword fallback trigger conditions, `meta.mode` signalling, the distinction between indexing attached source documents rather than the records, `rerank_score` sign meaning, and `empty_result.near_misses` on over-filtering. This is exactly the kind of context annotations cannot express.

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 two-mode split in bold labels and each sentence carries operational information. It is long and a few clauses (rerank score sign, near_misses) restate schema descriptions, but nothing is padding for its own sake.

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 9-parameter hybrid search tool with an output schema, the description covers modes, fallback semantics, coverage caveats, downstream id handoff, and scoping defaults — the remaining gaps (return format details) are handled by the output 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 100%, so the baseline is 3; the description nonetheless adds discriminating meaning — that `min_rerank` is the meaningful filter while `min_similarity` is coarse, that `dapper_content_id` is the record id to pass downstream, and that `country_code` omission differs from 'all'. It slightly duplicates the schema's own `min_rerank` text, keeping 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+resource+scope: cross-domain search over the full document corpus, with two explicitly named modes (`q` search vs `document_id` metadata fetch). It also names the sibling tools it overlaps with (domain list_* tools, get_document_text), so an agent can distinguish it 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 rules: use `q` unless `document_id` is given; prefer a domain tool's own `q` when the domain is already known; use `domain=` to scope; omit `country_code` only when you accept the default country. It also flags that empty results are inconclusive due to uneven coverage — a real usage caveat, not boilerplate.

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 destructiveHint=true and idempotentHint=true, but the description adds important operational context: it changes the signed-in person's data and requires a browser login rather than an API key. It also clarifies the idempotent behavior: unfollowing something not followed still succeeds.

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 short and mostly front-loaded, with the core action, auth requirement, idempotence, and usage hint all present. The opening clause about changing signed-in person's data is slightly generic before the specific action appears.

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 rich annotations, single required parameter, and existing output schema, the description covers what the agent needs: auth mode, watchlist-removal behavior, idempotence, and the relevant follow-limit workflow.

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 only parameter, bill_id, is already documented as 'The bill's own id.' The description does not add parameter-specific syntax, source, or format details beyond what the schema provides.

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: 'Removes a bill from this user's watchlist.' This clearly distinguishes it from follow_bill and from list_my_followed_bills, which only inspects follows.

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 usage cue: 'Useful right after FOLLOW_LIMIT_REACHED,' and points to list_my_followed_bills for deciding what to drop. It does not explicitly state when not to use the tool, but the 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?

Goes well past the annotations: discloses the auth model (browser login, not API key), the read-modify-write implementation detail about whole-set storage, and the destructive semantics of replace=true wiping everything unlisted. That matches destructiveHint=true without contradicting it and adds the 'why' 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?

Front-loaded with the most decision-relevant facts (auth, add-vs-replace) before details. Slightly long, and the '5 accounts out of 273' statistic is a tangent, though it does justify the tags exclusion in one clause.

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 mutation tool with an output schema and rich annotations, everything an agent needs is present: auth requirements, id discovery, add/remove/replace semantics, and the deliberate omission of tags. No key unknown is left for the agent to guess.

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 schema already says replace treats add_* lists as the complete profile, so the marginal value comes from the worked example (`add_entity_ids=[1635]` keeps the rest) and the explicit 'this adds and removes; it does not replace' framing. It does not map individual remove_* parameters, but the add/remove symmetry is obvious.

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 ('Changes the signed-in person's data... interest profile') and enumerates exactly what is mutated: entities, commissions and sectors. It also anchors the effect to a concrete observable ('what dapper://me reports and what personalises calls made without filters'), so an agent knows the blast radius.

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 rules: pass only what changes, use add_entity_ids to add one and keep the rest, and use replace=true only when explicitly requested. It also routes the agent to the right id sources (list_entities, list_commissions) and states why tags are not editable here, closing off a plausible wrong path.

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 destructiveHint=true and idempotentHint=true, so the description's added value is the auth constraint ("needs a browser login, not an API key") and the blast radius of changing country_code on all unfiltered queries — context the annotations cannot express. The one gap is that it never states what happens when a parameter is left null.

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 sentences, front-loaded with the auth constraint and the core effect, and the code-lookup pointer is well placed at the end. There is mild redundancy between the first line's "changes the signed-in person's data" and the second sentence's restatement of the same change.

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 annotations, a full output schema, and complete parameter descriptions available, the description covers what it must: auth method, fields affected, side effects on other tools, and where to get valid codes. Only the semantics of null/omitted parameters remain undocumented.

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 schema already documents both parameters, so the baseline is 3. The description adds the downstream fallback semantics of country_code and points to list_countries for code values, but does not clarify the meaning of an omitted/null field in this call itself.

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 ("Changes this user's preferred country or language") and scopes it to the signed-in person, which cleanly separates it from siblings like update_my_interests or list_countries. An agent can tell exactly what the tool mutates 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?

Gives real routing guidance: use list_countries to obtain valid codes, and the country_code preference feeds every other tool's default filtering. It does not explicitly say when to prefer update_my_interests instead, nor when not to call this, so it stops just 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.