va-lis-mcp

search_bills

Search a session's bills by keyword, stage, patron, or chapter number.

Instructions

Search a session's bills by keyword, stage, patron, or chapter number.

This is the full text search; list_bills only matches the number and the short description. keyword searches the summaries, or the bill text when search_in is "Bill Text", and takes AND, OR, and parentheses ("firearm AND ammunition"). LIS drops common words, so "the" finds nothing. category is a stage a bill reached, by name: "In Committee", "Passed House", "Continued", "Vetoed", "Acts of Assembly chapters"; an unknown name answers with the full list. member_id narrows to one patron in any role. chapter finds the bill behind an Acts of Assembly chapter (350 finds CHAP0350). At least one of the four is required.

One row per bill, in LIS order, with status, chapter, chief patron, and the committee that holds the bill. include_summaries adds the plain text of each bill's furthest-along summary. A keyword search on its own includes failed bills; with category or member_id LIS leaves out failed and incorporated bills. limit is capped at 200; page with offset.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "session_code": "<session_code>"
    },
    "name": "search_bills"
  }
}

Input Schema

Name	Required	Default
`limit`	No
`offset`	No
`chamber`	No
`chapter`	No
`keyword`	No
`category`	No
`member_id`	No
`search_in`	No	Summary
`session_code`	Yes
`include_summaries`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.2.0Oct 13, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so well: it discloses LIS stop-word dropping ('"the" finds nothing'), that an unknown category returns the full valid list, that a bare keyword search includes failed bills while category/member_id filtering excludes failed and incorporated bills, and that limit is capped at 200 requiring offset paging. That is unusually rich behavioral context.

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

Conciseness4/5

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

Purpose is front-loaded and the three paragraphs map cleanly to purpose, parameter semantics, and return shape, with no filler sentences. It runs long, but the length is largely justified by ten undocumented parameters and no schema descriptions.

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

Completeness4/5

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

For a complex tool with no annotations and no output schema, the description supplies the return row shape (status, chapter, chief patron, holding committee) and the effect of include_summaries. It leaves the chamber filter and the meaning/source of session_code unexplained (no pointer to list_sessions), which is the main remaining gap.

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

Parameters4/5

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

Schema coverage is 0%, so the description must compensate, and it documents keyword syntax, search_in, category values, member_id scoping, chapter format (350 → CHAP0350), include_summaries, and the limit/offset interaction. The chamber parameter is never mentioned, and session_code is only implied by 'a session's bills', leaving two parameters semantically thin.

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

Purpose5/5

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

Opens with a precise verb+resource+facets ('Search a session's bills by keyword, stage, patron, or chapter number') and explicitly demarcates itself from the sibling list_bills ('only matches the number and the short description'). An agent can route between the two 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.

Usage Guidelines5/5

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

States the selection condition against list_bills, explains that at least one of keyword/category/member_id/chapter is required, and clarifies the differing semantics of each route (keyword vs category vs member_id vs chapter). It also warns about LIS stop-word behavior so the agent does not mis-select this tool for common-word lookups.

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