UK Data: UK Parliament votes

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior, and the description adds substantial context beyond that: pagination caps of 100 per side, a cost of 1 credit, and the important semantic warnings that 'no vote recorded' is not abstention and that published name lists can differ from official totals by one or two (with members_in_both_lobbies flagging duplicates).

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 payload description is front-loaded in sentence one, and the trailing sentences each carry distinct information (paging limits, the abstention distinction, the teller/list mismatch caveat, and credit cost). It is dense with parentheticals and one long run of clauses, but no sentence 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?

With no output schema, the description carries the return-value burden itself, and it names the key result fields (totals, winning side, party split, rebels, list_vs_official_count, members_in_both_lobbies) so the agent knows what it will receive. It also advises on pagination and the required division_id, matching the complexity of a single-resource lookup.

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 each parameter already documents its type, range and default, so the description does not need to restate them. It only adds framing that the MP lists come back in pages of up to 100 per side with party filtering and offset paging, which is a marginal restatement of the schema 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?

The description opens with a specific verb+resource ('Get the full result of one House of Commons vote') and enumerates the payload: totals, winning side, party split, intra-party rebels, and names/constituencies per side. This clearly distinguishes it from commons_division_search, which is named as the source of the division_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?

It gives a concrete entry condition ('Use a division_id from commons_division_search'), two motivating questions it answers ('who voted against?', 'how did my MP vote?'), and a paging caveat. It does not explicitly state when to prefer lords_division_result instead, so the alternative routing is only implied by the 'House of Commons / UK Parliament' framing.

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's job is to add context beyond safety. It does: newest-first ordering, the fields returned (Aye/No totals, winning side, tellers), the upstream source, and a 1-credit cost. It does not cover empty-result behavior or result-count limits beyond what the schema states, keeping it short of a 5.

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

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

The primary purpose and the question it answers are front-loaded, with the exclusion and the sibling pointer following. The opening sentence is long and packs the return fields into one clause, but no sentence 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?

With no output schema, the description steps in to name the returned fields (totals, winner, tellers) and the ordering, plus the source and cost. That is nearly complete for a two-parameter search tool; only edge-case behavior for zero matches is 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 both q and take are already documented with types and examples. The description restates that matching is on the division title only, which reinforces but does not materially extend the schema's own wording. Baseline 3 is appropriate when the schema carries the 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?

States a specific verb and resource: find House of Commons divisions whose title contains a keyword. It scopes the domain (UK Parliament Commons Votes API) and distinguishes itself from the sibling commons_division_result, which it names explicitly.

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 in the user's own phrasing ("did MPs vote on X and what was the result?") plus an explicit exclusion: matches division titles only, not debate text. It also routes the agent to commons_division_result when MP names per side are needed, which is exactly the when-to-use-this-vs-alternative guidance the dimension asks for.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: the upstream source (UK Parliament Commons Votes API), a publication lag of usually under an hour, a 1-credit cost, and the result field set. The only missing piece is pagination/windowing behavior beyond the take cap, which is minor for a read-only list.

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 operation and its output shape are front-loaded in the first clause, followed by use case, source, freshness caveat, and sibling routing in descending priority. No sentence is redundant and the parenthetical cost note is compact and last, where it belongs.

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

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

There is no output schema, so the description must carry the return-value burden, and it does by listing date, time, title, Aye/No totals, and the winning side. Combined with the freshness caveat and the sibling routing for deeper detail, an agent has everything needed to call this correctly and interpret the 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 coverage is 100% and the single optional parameter is fully documented in the schema with its type, range 1-25, and default of 10. The description adds only the implicit notion of "latest" and "newest first" ordering, which the schema does not state but which is really result semantics rather than parameter semantics. Baseline 3 applies since the schema carries the parameter load.

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?

"List the latest House of Commons votes, newest first" names a specific verb, resource, and ordering, then enumerates the returned fields (date, time, title, Aye/No totals, winning side). It also explicitly differentiates itself from commons_division_result and lords_division_search, so an agent can pick it out of a very large sibling list 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?

It gives a concrete use-case trigger ("what did MPs vote on today or this week?") and names two alternatives with the condition that selects each: commons_division_result for per-member names via a division_id, and lords_division_search for Lords votes. The publication-latency note also tells the agent when this tool will not yet have the data it wants.

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 bar is lower, and the description still adds real behavioral detail: per-side lists cap at 100 peers, party filter and offset page through the remainder, and peers who did not vote are omitted entirely. That last caveat prevents a serious misreading of the data. The 1-credit cost is also disclosed; only error behavior for an invalid divisionId is unaddressed.

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

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

Front-loaded with what is returned, then the use-case question, then source, then pagination caveats. Dense but every clause carries information; the parenthetical credit cost is a slightly tacked-on addition but still useful. 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 no output schema, the description carries the full burden of describing the return payload, and it does so field by field — totals, government result, party split, rebels, and per-side peer lists. Combined with the pagination and non-voter caveats, an agent has everything needed to call it and interpret results 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 3 is the baseline, but the sentence 'Lists return up to 100 peers per side, with party filter and offset for the rest' explains how limit, party, and offset interact over the same per-side lists in a way the individual schema strings do not. That interaction semantics is the added value.

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

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

States a specific verb and resource ('Get the full result of one House of Lords vote') and then enumerates exactly what that result contains: motion/amendment text, Content and Not Content totals, government outcome, party split, rebels, and individual peer lists. The House of Lords scoping separates it cleanly from commons_division_result, and the single-division scope separates it from lords_division_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?

Gives clear context for when the tool is the right one, including the concrete question it answers ('which peers voted against the government?'). It does not explicitly state the prerequisite of calling lords_division_search first for a divisionId (that hint lives only in the schema), and it names no exclusion conditions.

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, non-destructive), and the description adds value beyond that: default ordering (newest first), the fields returned (motion/amendment moved, Content/Not Content totals, winning side, government win/defeat), the upstream source, and a cost of 1 credit. The credit cost in particular is operational context no annotation provides.

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 action and scope, with the escape hatch to lords_division_result and the credit cost placed at the end where they belong. The middle sentence is a dense field list, but every listed field is informative 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 no output schema, the description takes on the job of describing return contents and does so explicitly, plus ordering, source, and cost. For a two-parameter read-only search tool, an agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100%, so both q and take are already documented, and the description only restates that searching is by keyword. It does not explain take limits or truncation behavior, so it adds little beyond the schema — the expected 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 ('Find House of Lords votes (divisions)'), the query mode ('by keyword, newest first'), and the exact shape of the answer it returns. It is cleanly separable from commons_division_search (Commons) and lords_division_result (peer-level detail) 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?

Gives a concrete question it answers ('did the Lords defeat the government on X?') and explicitly routes to lords_division_result when peer names are needed. It stops short of stating when NOT to use it (e.g. Commons divisions, or when a specific division ID is already known), so it is strong but not fully exhaustive.

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