Server Quality Checklist

Tool Scores

• search_billsA
  4/5.0
  Behavior3/5

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

  Annotations already indicate readOnlyHint=true, so the description doesn't need to reiterate. It adds no further behavioral traits like rate limits or authorization needs, and the output description is about result format, not behavior.

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

  Conciseness5/5

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

  Two sentences, front-loaded with action and scope, no wasted words. Efficient and clear.

  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?

  The description explains the output format (teasers with headline, status, urgency) and ordering (most urgent first), which is important since there is no output schema. It covers the main search dimensions but lacks differentiation from sibling tools.

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

  Parameters3/5

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

  The description gives a high-level summary of parameter usage (free-text, topic, status, active-only) but adds no meaning beyond the schema. Schema coverage is 100%, so baseline 3 is appropriate.

  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?

  The description clearly states the tool searches Oravan's bilingual federal bill corpus by multiple criteria (free-text, topic, status, active-only) and returns teasers. It distinguishes from siblings like get_bill by being a search function over a corpus.

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

  Usage Guidelines4/5

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

  The description implies usage for finding bills via criteria but does not explicitly contrast with sibling tools such as get_bill, get_representative, or whats_moving. However, the context of search vs. single-bill retrieval is clear.

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

• whats_movingA
  4.1/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true. The description adds valuable behavioral context: it returns an honest empty list, never pads results, and distinguishes between quiet_week and data_stale. This goes beyond the annotations without contradicting them.

  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?

  The description is well-structured, starting with the core purpose, then adding edge-case details. It is efficient, but slightly longer than necessary; a shorter version could preserve all key points.

  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?

  With no output schema, the description compensates by explaining the return behavior (quiet_week, data_stale). It covers the filtering criteria and output shape adequately for the tool's complexity. However, it could mention the fields of the returned bills.

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

  Parameters3/5

  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 restates defaults (7 days, limit 10) already in the schema, but adds no new semantic detail beyond what the schema provides. Thus, it does not significantly enhance parameter understanding.

  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?

  The description clearly identifies the resource as 'active, plain-language-decoded bills' that cleared an urgency bar, with optional topic filtering. It distinguishes from siblings like search_bills (broader search) and get_bill (single bill), making the purpose specific and unambiguous.

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

  Usage Guidelines4/5

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

  The description explains when to use (to find urgent bills) and details edge cases like quiet_week and data_stale, which guide appropriate usage. However, it does not explicitly state when to avoid this tool in favor of siblings like search_bills.

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

• get_representativeA
  4.2/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint=true, confirming no side effects. The description adds behavioral traits: returns exactly 5 most recently active sponsored bills and limits to factual data. It does not contradict annotations and provides useful context about what is included and excluded.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the core purpose. Every sentence adds value: first sentence defines the tool, second sentence clarifies constraints. No unnecessary words or repetition.

  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?

  Given no output schema, the description provides a good sense of the response: 'full details' plus 5 bills. It covers the key constraints (by bioguide, facts only) and is sufficient for agent decision. Minor lack of exact field names, but overall complete for this simple tool.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already explains both parameters (bioguide ID example, locale options). The description reinforces the bioguide example but does not add new meaning beyond what is in the schema. Thus baseline score of 3 is appropriate.

  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?

  The description clearly states the verb 'Get', the resource 'full details for one member of Congress', and the method 'by bioguide ID'. It also specifies additional included data (5 most recently active sponsored bills). This distinguishes it from sibling tools like lookup_representatives (search) and get_bill (bill-focused).

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

  Usage Guidelines4/5

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

  The description includes 'Facts only: no scorecards, ratings, or vote grades,' which informs the agent when not to use this tool (i.e., when opinionated data is needed). It implicitly suggests using this when you have a bioguide ID and require comprehensive details plus recent bills, though alternatives are not explicitly named.

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

• get_billA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint: true and openWorldHint: false, and the description adds valuable context: AI summaries are auto-checked before publishing, citation resolution defaults to the most recent Congress, and script generation is not available through the API. This goes beyond the base annotations, though it could mention error behavior or data freshness.

  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?

  The description is a single, dense sentence but is structured logically, starting with the core action and then detailing the return payload and a key limitation. It is verbose yet every phrase contributes meaningful detail, with no fluff. Breaking it into two sentences could improve readability without adding bulk.

  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?

  The description covers the main aspects: purpose, input methods, output fields (summary, status, urgency, sponsor, dates, URLs), and a critical limitation. Given the tool's moderate complexity and absence of an output schema, this is largely complete. Minor gaps include no mention of error conditions, rate limits, or handling of invalid slugs/citations, which could be inferred from typical API behavior.

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

  Parameters5/5

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

  While the schema provides basic parameter descriptions, the tool description enriches understanding by explaining that slug takes priority over citation, how citations are resolved, and gives realistic examples. The explicit mention of the precedence rule and the 'most recent Congress' behavior adds semantic value that the schema alone does not convey. This helps the agent use parameters correctly.

  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?

  The description clearly states the tool's purpose: getting a full plain-language decode of a federal bill using either a slug or citation. It distinguishes itself from sibling tools by focusing on bill-specific data and explicitly noting it never drafts a phone script, setting it apart from the on-site call flow and other tools.

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

  Usage Guidelines4/5

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

  The description explains how to invoke the tool (by slug or citation) and the priority of slug over citation, which helps in usage. It also clarifies a limitation (no script drafting). However, it does not explicitly compare this tool to siblings like search_bills or what to do when a bill ID is unknown. A direct 'when to use this instead of search_bills' would be an improvement.

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

• lookup_representativesA
  4.5/5.0
  Behavior5/5

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

  Adds rich context beyond annotations: details on multi-district behavior, vacancy handling, and the reps_url proxy, ensuring agents understand exactly what the tool does and its limitations.

  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?

  The description is thorough but slightly verbose; however, every sentence adds value and it is well-structured with front-loaded purpose.

  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?

  Covers major edge cases (multi-district, vacancies) and return fields, but lacks explicit output schema; still complete enough for a lookup tool given the context.

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

  Parameters3/5

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

  Schema coverage is 100%, so baseline is 3. Description confirms usage of zip and locale but does not add significant parameter-specific details beyond the schema.

  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?

  The description clearly states it looks up U.S. House member and two Senators by 5-digit ZIP code, listing returned fields and handling of multi-district ZIPs and vacancies, distinguishing it from sibling tools like get_representative.

  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?

  Explicitly explains when to use (by ZIP), limitations (multi-district ZIPs require address refinement), and how vacancies are handled, providing clear guidance on when not to use this tool alone.

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