Where a UK bill, treaty or statutory instrument is in Parliament: stages, sponsors, amendments
Score is being calculated.
Lists bills that have received Royal Assent and become Acts of Parliament, most recent first, with the Royal Assent date and the Act's title. For compliance, HR and legal teams who need to hear about new Acts quickly. Source: UK Parliament Bills API. It covers UK Parliament Acts only, not commencement dates or statutory instruments, and does not show the Act text (see legislation.gov.uk). (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| take | No | integer, optional, Acts to return 1-100, default 10 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely useful context beyond that: result ordering, the exact fields surfaced, the source (UK Parliament Bills API), explicit coverage limits, and a cost of 1 credit. It stops short of describing result volume or whether a total count is returned.
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 action and ordering, followed by scope exclusions, source and cost. The audience clause is the weakest element but is short and immediately followed by the limits that matter for correct invocation.
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-parameter read tool with full schema coverage, full annotation coverage and no output schema, the description covers what is returned, ordering, source, scope limits and cost. The only gap is that it does not say whether results are effectively capped/paged or how fresh the underlying data is, which matters for a 'recent' monitoring 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% — the sole 'take' parameter already documents range 1-100 and default 10. The description adds only the ordering meaning ('most recent first') that makes 'take' interpretable as 'the N newest Acts', but never references the parameter or clarifies behaviour above 100 or absence of paging.
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 (lists bills receiving Royal Assent that became Acts of Parliament), plus ordering ('most recent first') and the fields returned (Royal Assent date and Act title). It also bounds the scope against adjacent data ('UK Parliament Acts only, not commencement dates or statutory instruments'), which separates it from sibling tools such as statutory_instrument_search and bill_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?
Usage is only implied through an audience statement ('compliance, HR and legal teams who need to hear about new Acts quickly') plus exclusions (no commencement dates, no Act text, see legislation.gov.uk). It never names a sibling alternative such as legislation_search, bill_status or bills_recently_updated, so the agent must infer routing itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the amendments tabled at one stage of a UK bill, with the clause or schedule targeted, the amendment wording, its sponsors and the decision recorded (agreed, negatived, withdrawn, not moved). For public affairs teams and campaigners tracking whether an amendment got through. Source: UK Parliament Bills API. Needs the bill ID and a stage_id from bill_stages_timeline; can filter by decision or a word in the amendment, and pages with skip. Decisions are null until Parliament records them. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | integer, optional, amendments to skip for paging, 0-100000, default 0 | |
| take | No | integer, optional, amendments to return 1-100, default 25 | |
| billId | No | integer, required, the Parliament bill ID, e.g. 4035 | |
| search | No | string, optional, word or phrase in the amendment text, e.g. ombudsman | |
| decision | No | string, optional, only amendments with this recorded decision: agreed, agreed_on_division, withdrawn, withdrawn_before_debate, disagreed, negatived_on_division, not_moved, not_selected, not_called, no_decision, question_proposed, stood_part, not_stood_part, preempted; default all | |
| billStageId | No | integer, required, the stage_id from bill_stages_timeline, e.g. 21180 |
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's job is to add operational context — and it does: data source, a 1-credit cost, and the important caveat that decisions are null until Parliament records them. It does not describe pagination limits or default page size, which the schema carries instead.
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 and its return shape, then prerequisites, then filters, then caveats — a sensible order. The audience sentence ('For public affairs teams and campaigners…') is the one line that is more positioning than instruction, though it is short.
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 six parameters and no output schema, the description compensates by summarizing what each amendment record contains and warning about null decisions. Only missing piece is pagination/response-shape detail, which is minor against an otherwise complete picture.
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 exceeds it by adding provenance the schema lacks — that billStageId must come from bill_stages_timeline — and by framing skip as paging and decision/search as filters. It doesn't reconcile the mismatch between the schema's 'required' wording and the tool's reported 0 required 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?
States a specific verb and resource — lists amendments tabled at one stage of a UK bill — and enumerates the returned content (clause/schedule targeted, wording, sponsors, recorded decision). That scope is clearly distinct from siblings like bill_stages_timeline and bill_documents, so the agent can pick 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?
Names the prerequisites precisely and routes the agent to the correct sibling for the stage_id (bill_stages_timeline), plus explains the two filtering modes and paging. It stops short of stating exclusions (e.g. cross-stage or all-amendments queries), so it is strong context rather than a full when/when-not pair.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the documents published for a UK bill, newest first: bill texts, explanatory notes, amendment papers, impact assessments, delegated powers memoranda and committee reports, with direct PDF and web links. For lawyers and policy staff after the latest bill text or notes. Source: UK Parliament Bills API. It returns links, not the document text; pair it with a URL or PDF reader to read one. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | integer, optional, documents to return 1-100, default 25 | |
| billId | No | integer, required, the Parliament bill ID (from bill_search), e.g. 3462 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behaviour beyond that: results are ordered newest-first, the payload contains links rather than document text, and each call costs 1 credit. Pagination behaviour and what happens at the 100-document cap are not disclosed, which keeps it off 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 verb and scope, then document types, then audience, then the critical caveat that links are returned rather than text. Every sentence earns its place and the caveat is placed before an agent could mistake this for a full-text tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates fully by saying the response is a newest-first list of PDF/web links rather than document bodies. For a two-parameter read tool with rich annotations, nothing needed to invoke or interpret 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 description coverage is 100%, so the schema already documents both limit and billId (including the bill_search provenance and an example ID). The description adds only the newest-first ordering, which is implicit sorting context rather than parameter meaning; a baseline 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 ("Lists the documents published for a UK bill") and then enumerates the exact document classes returned (bill texts, explanatory notes, amendment papers, impact assessments, delegated powers memoranda, committee reports). This enumeration separates it from neighbours like bill_amendments, bill_status and bill_stages_timeline without the agent needing to open 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 clear situational context ("For lawyers and policy staff after the latest bill text or notes") and a follow-up routing hint ("pair it with a URL or PDF reader to read one"). It stops short of naming a specific alternative tool or stating when not to use it, so it is clear context rather than full 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.
Finds UK Parliament bills whose title matches a keyword, newest-updated first so current bills come before old ones, with each bill's ID, type, current stage and house, whether it became an Act, and a link to its Parliament page. For journalists, landlords, campaigners and students asking "is there a bill about X". Source: UK Parliament Bills API, which covers recent parliamentary sessions; older bills may be missing. It matches bill titles only, not bill text, and does not cover Scottish, Welsh or Northern Ireland legislatures. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | string, required, word or phrase in the bill title, e.g. renters | |
| skip | No | integer, optional, matches to skip for paging (results are newest-updated first), 0-100000, default 0 | |
| take | No | integer, optional, results to return 1-100, default 10 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses result ordering (newest-updated first), the fields each record carries (ID, type, stage, house, became-an-Act flag, Parliament link), the source API's coverage of recent sessions only, and a per-call credit cost. Those coverage and cost caveats are exactly the kind of context annotations cannot convey.
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 purpose and return shape in the first sentence, with limitations and audience in following sentences. The trailing credit note is slightly tacked on and the first sentence is long, but nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only search with no output schema, the description covers the query semantics, result ordering, returned fields, data coverage limits and cost — everything an agent needs to decide to call it 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 each parameter already carries its own description, so the description only echoes the newest-updated ordering that the skip parameter already documents. No extra meaning about matching behaviour (e.g. whether keywords are ANDed or ORed, case sensitivity) is added.
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 ("Finds UK Parliament bills whose title matches a keyword") and narrows scope beyond the name: title matching only, not bill text, and excludes Scottish, Welsh and Northern Irish legislatures, which separates it from legislation_search and statutory_instrument_search. An agent can pick this over bills_recently_updated or bill_status 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 a concrete usage scenario ("is there a bill about X" for journalists, landlords, campaigners and students) plus explicit exclusions — title-only matching and missing older bills. It does not name a direct alternative sibling for full-text or historical searches, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the UK Parliament bills whose records changed most recently, with current stage, house, upcoming or latest sitting dates and status. A quick "what is moving through Parliament" view for public affairs teams and journalists. Source: UK Parliament Bills API. Ordered by when Parliament last updated the bill record, which usually but not always reflects new parliamentary activity. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| take | No | integer, optional, bills to return 1-100, default 10 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description goes beyond that with substantive context: the ordering key (Parliament's last record update), an honest caveat that this "usually but not always reflects new parliamentary activity," the upstream source, and a 1-credit cost.
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 returned fields and the recency framing are front-loaded, and the ordering caveat and cost are appended efficiently. The audience sentence ("for public affairs teams and journalists") is mild filler but also carries usage signal, 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?
There is no output schema, and the description compensates by enumerating the fields returned (stage, house, dates, status). Combined with the ordering semantics, source attribution and credit cost, the agent has enough to call and interpret it; only the result count behavior 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 the single `take` parameter is fully documented in the schema (integer, 1-100, default 10). The description adds nothing about it — no mention of the default page size or the maximum — so with the schema doing all the work, 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?
The description names a specific verb and resource ("Lists the UK Parliament bills whose records changed most recently") and enumerates the returned fields (stage, house, sitting dates, status). It clearly reads as a recency-ordered feed rather than a lookup, which separates it from bill_search or bill_status, but it never names those siblings to make the contrast explicit.
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?
"A quick 'what is moving through Parliament' view for public affairs teams and journalists" establishes the intended use case and audience, which implies when to reach for it. However, there is no explicit when-not guidance and no pointer to alternatives such as bill_search (lookup by name) or bill_status (single bill detail), so the agent must infer routing from the sibling names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists every stage a UK bill has been through or has scheduled, in order, with the house and each sitting date: first and second reading, committee, report, third reading, Lords stages, consideration of amendments, Royal Assent. Saves researchers and public affairs teams from piecing together a bill's passage by hand. Source: UK Parliament Bills API. It gives dates, not debate content or votes; each stage_id can be passed to bill_amendments. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| billId | No | integer, required, the Parliament bill ID (from bill_search), e.g. 4035 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description earns credit for additions: the upstream source (UK Parliament Bills API), a cost of 1 credit, and the non-obvious trait that it returns not only historical stages but also scheduled future ones. It does not detail ordering guarantees beyond 'in order' or how incomplete/withdrawn stages appear.
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 capability and the stage enumeration are front-loaded, and the follow-on tool, exclusion, source and cost notes are compact. The 'Saves researchers and public affairs teams...' sentence is mild marketing that consumes space without adding agent-relevant 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?
There is no output schema, so the description must convey the return content, and it does reasonably well: ordered stages, house, sitting dates, and the stage_id hook. It does not describe the response envelope or how multi-house/committee stages are nested, a minor gap for a single-parameter read tool whose annotations already establish safety.
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 a single parameter and 100% schema description coverage (billId is documented as the Parliament bill ID from bill_search with an example), the schema already carries the meaning. The description adds nothing about billId — the only ID it discusses, stage_id, is a return value — so 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 ('Lists every stage a UK bill has been through or has scheduled') and enumerates the stage types returned (first/second reading, committee, report, third reading, Lords stages, consideration of amendments, Royal Assent). It also names the sibling bill_amendments as the follow-on tool, so an agent can tell it apart from adjacent bill tools 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?
Provides clear context for use (tracing a bill's passage, saving manual assembly) plus an explicit exclusion — 'dates, not debate content or votes' — and a routing hint that stage_id feeds bill_amendments. It stops short of naming alternatives for the cases it excludes (e.g. bill_documents or bill_status for content/status), so it is short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shows where one UK bill is now: its current stage and house with sitting dates, whether it has become an Act, been withdrawn or defeated, its long title and its sponsoring members and departments. Answers "where is the X bill now", "has it passed" and "who introduced it". Source: UK Parliament Bills API. Needs the bill ID from bill_search; it does not predict when a bill will pass. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| billId | No | integer, required, the Parliament bill ID (from bill_search), e.g. 3462 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover the safety profile (read-only, idempotent, non-destructive, open-world), so additional disclosure is optional. The description still adds real context: the source is the UK Parliament Bills API, the call costs one credit, and the tool deliberately does not forecast outcomes.
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 sentence is long and front-loads the scope; the following sentences add only useful detail (example questions, source, prerequisite, exclusion, cost). Nothing is filler, though the opening sentence could be split for easier 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?
There is no output schema, and the description compensates by enumerating the fields that come back. Combined with the annotations covering safety and a fully documented single parameter, it gives enough information to call the tool correctly without guessing; only the exact response shape remains unspecified.
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 describes billId as the Parliament ID from bill_search with an example. The description's note that it needs the ID from bill_search largely restates the schema, adding little beyond 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?
The description names a specific resource and scope: the current state of a single UK bill, including stage, house, sitting dates, Act/withdrawn/defeated status, long title, and sponsors. It is clearly distinguishable from bill_search (which supplies the ID) and from timeline or amendment 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?
It states the questions it answers ("where is the X bill now", "has it passed", "who introduced it"), requires that the bill ID come from bill_search, and explicitly excludes prediction of passage dates. It does not, however, route to sibling tools such as bill_stages_timeline or bill_amendments when those are better fits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds statutory instruments (regulations and orders) laid before the UK Parliament by words in their name, with the procedure they follow (for example draft affirmative or negative), laying dates in each House, made date and SI number where issued. For compliance and legal teams asking what regulations were just laid on a topic and how Parliament will deal with them. Source: UK Parliament Statutory Instruments API. It covers laying and procedure, not the regulation text (see legislation.gov.uk). (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | string, required, word or phrase in the instrument name, e.g. pension | |
| take | No | integer, optional, results to return 1-100, default 10 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's job is to add operational context. It does: it names the upstream source (UK Parliament Statutory Instruments API), states the credit cost, and describes the coverage boundary (procedure and laying, not text). It does not discuss pagination/result-cap behaviour beyond what 'take' implies, so it stops short of fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with purpose, then audience/use case, then source, then coverage boundary and cost — a logical ordering with no filler. It is slightly denser than necessary (audience sentence overlaps with the purpose), but every clause conveys real 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?
With no output schema, the description correctly carries the return-value burden by enumerating the result fields an agent will see. For a two-parameter, read-only lookup with full annotation coverage, the only meaningful gaps are result-ordering and what an empty result means.
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, ranges and an example. The description's 'by words in their name' restates the schema's own 'word or phrase in the instrument name, e.g. pension' rather than adding syntax, matching rules or behaviour for zero-hit queries. Baseline 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?
The description states a specific verb and resource ('Finds statutory instruments ... laid before the UK Parliament by words in their name') and immediately enumerates the fields returned (procedure, laying dates per House, made date, SI number). It also explicitly distinguishes itself from the regulation-text tools by pointing to legislation.gov.uk, so an agent can separate it from legislation_search and legislation_text 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?
It gives a concrete use case ('compliance and legal teams asking what regulations were just laid on a topic and how Parliament will deal with them') and an explicit exclusion ('covers laying and procedure, not the regulation text'). What it lacks is a named sibling alternative within this toolset (e.g. legislation_search / legislation_text) rather than only an external site, so the routing is clear but not fully internal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds treaties laid before the UK Parliament by keyword, with the treaty name, command paper number, treaty series citation, signed and laid dates, lead department, whether the scrutiny period has concluded so the Government can ratify, and any scheduled debate. For trade lawyers, exporters and academics checking UK treaty scrutiny under the Constitutional Reform and Governance Act 2010. Source: UK Parliament Treaties API. It does not give treaty text beyond a GOV.UK link. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | string, required, word or phrase in the treaty, e.g. trade | |
| take | No | integer, optional, results to return 1-100, default 10 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the bar is lowered; the description still adds real value by naming the source API, disclosing a cost of 1 credit, and stating the key limitation that full treaty text is not returned. It does not cover pagination or result ordering, which keeps it below 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?
Purpose is front-loaded in the first clause, followed by return fields, audience, source, limitation and cost. The long field enumeration makes the opening sentence dense, but every element carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the returned fields and flags the missing treaty text, and it identifies the data source. For a two-parameter keyword search this is nearly complete; only result count/pagination behavior 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 description coverage is 100%, so the baseline is 3. The description only restates keyword searching and adds no guidance on phrase handling, matching behavior, or use of the 'take' range beyond what the schema already says.
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 ('Finds treaties laid before the UK Parliament by keyword') and enumerates the returned fields (command paper number, treaty series citation, signed/laid dates, lead department, scrutiny status, debate). This is clearly distinguishable from nearby siblings such as legislation_search, statutory_instrument_search and papers_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?
Names the audience and use case (trade lawyers, exporters, academics checking scrutiny under the Constitutional Reform and Governance Act 2010) and gives one explicit exclusion ('does not give treaty text beyond a GOV.UK link', implying govuk_page for full text). It stops short of naming an alternative tool or stating when a different search tool should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
acts_recent_royal_assentbill_amendmentsbill_documentsbill_searchbill_stages_timelinebill_statusbills_recently_updatedstatutory_instrument_searchtreaty_searchSearch UK Parliament bills, members, votes, Hansard, written questions, and committees.
UK legislation full text, MPs, petitions, GOV.UK search, food alerts, police neighbourhoods
Search and read UK legislation at any date, resolve citations, list amendments, track changes.
UK select committees: members, inquiries, witnesses and published reports from Parliament
Add one secure layer between your agents and this server.