Govbase

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

Annotations already include readOnlyHint=true, and the description adds value by detailing the returned data structure (lineage, status, coverage). This goes beyond the annotation without contradicting it.

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 one well-structured sentence with a front-loaded action ('Retrieve an effort by ID') followed by a concise list of return items. No wasted words.

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, so the description's enumeration of return contents (answer, lineage, status, next actor, coverage) provides sufficient completeness for a one-parameter retrieval 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%, with effort_id already described with an example. The description does not add parameter-specific detail beyond saying 'by ID', which is appropriate given 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 clearly states 'Retrieve an effort by ID' and enumerates specific content (plain-language answer, bill lineage, status, next actor, story coverage), making it distinct from sibling tools like get_policy or get_story.

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 implies when to use this tool—when effort details by ID are needed—but does not explicitly exclude alternatives or reference sibling tools. It provides clear context without exclusions.

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 annotation readOnlyHint=true already covers the safety profile, and the description's 'Retrieve' is consistent. The description adds little beyond the lookup condition (e.g., no mention of not-found behavior or return format), but the annotation lowers the burden, so a mid-range score is appropriate.

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 a single front-loaded sentence containing the verb, resource, method, and an example, with no wasted words. It fully informs in 18 words.

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 this is a simple lookup with one parameter and no output schema, the description is largely complete: it explains what the tool does, how to invoke it, and gives an example. It does not detail the fields of the returned information, but 'detailed information' is a reasonable summary for this low-complexity 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%, with the parameter description already giving the example 'P000197'. The tool description repeats that example and adds 'U.S. member of Congress' context, but this does not add significant meaning beyond what the schema already provides, hence the baseline score of 3.

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 ('Retrieve'), resource ('detailed information about a specific U.S. member of Congress'), and method ('by their Bioguide ID'). It distinguishes itself from siblings like search_members (search) and get_member_vote (vote details), making the purpose 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 clearly implies when to use the tool: when you have a Bioguide ID and need member details. However, it does not explicitly mention when not to use it or direct users to alternatives like search_members when the ID is unknown, so it lacks explicit exclusion/alternative 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?

The readOnlyHint annotation already indicates a safe read operation. The description adds value by specifying that it returns 'all roll call votes' for that member on the policy, giving insight into the output without contradicting the annotation.

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 concise sentences that are front-loaded with the main action. No wasted words; every part contributes to understanding the tool's function.

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 tool with two required parameters and no output schema, the description fully covers what the tool does and what it returns. No additional context seems necessary for correct invocation.

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%, with both parameters described clearly. The description reiterates the purpose of the IDs but does not add much beyond the schema. Baseline of 3 is appropriate since the schema handles parameter 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 clearly states the tool's purpose: checking how a specific U.S. member of Congress voted on a policy using Bioguide ID and policy ID. It distinguishes itself from siblings like get_member and get_policy by focusing on the member's vote on a specific policy.

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 clarifies when to use the tool: when you have a specific member's Bioguide ID and a policy ID. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to infer appropriate usage.

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 readOnlyHint annotation already communicates that this is a safe read operation. The description adds the ID format examples but no additional behavioral details about return format, pagination, or what constitutes 'detailed information'. It does not contradict the 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?

A single concise sentence that immediately states the verb, resource, and identifier format. No redundant 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?

The tool is simple with one parameter and read-only annotation, but the description does not clarify what information is returned or differentiate from the sibling get_policy_text tool. The lack of an output schema makes this somewhat incomplete for an agent to know what to expect.

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 fully describes the single parameter policy_id with the same examples as the description. The description adds no additional meaning 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 description clearly states the tool retrieves detailed information about a specific U.S. federal policy by ID, with concrete ID examples. It distinguishes from get_policy_text implicitly by saying 'detailed information' rather than 'text', but does not explicitly differentiate.

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?

No guidance on when to use this tool vs alternatives like get_policy_text or search_policies. It does not mention any exclusion or alternative tools, so the agent must infer when to use this.

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 provide readOnlyHint=true, and the description aligns with that by using 'Retrieve' and 'Returns'. It adds the context that the text is 'raw legislative or regulatory', but does not disclose other behaviors such as pagination or response size. Given the annotation coverage, this is adequate but not rich.

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 two sentences, front-loaded with the action and resource. No redundant or filler content; every word 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 simple retrieval tool with two well-described parameters and a readOnlyHint, the description covers the essential purpose and return type. It could mention that the text is returned in full without pagination, but 'full text' already implies this. It is nearly complete.

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 both policy_id and format having descriptions. The tool description does not add additional parameter meaning beyond the schema, 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?

The description clearly states the tool retrieves the full text of a U.S. federal policy document and returns the raw legislative or regulatory text. This distinguishes it from siblings like get_policy (likely metadata) and search_policies, using a specific verb and resource.

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 implies when to use the tool (when full text is needed) but does not explicitly mention alternatives or exclusions. Sibling tools like get_policy might serve similar but different purposes, yet no direct comparison is provided.

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?

With readOnlyHint=true annotation, the agent already knows this is a safe read operation. The description adds useful context about the levels of officials returned but doesn't disclose additional behaviors like address validation or error handling. Given the annotation coverage, this is adequate but not exceptional.

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 a single, well-structured sentence that front-loads the action and clearly states the input and output scope. Every phrase earns its place with no 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?

For a simple one-parameter tool without an output schema, the description sufficiently covers the tool's purpose, input, and expected return categories. It doesn't detail response format or error conditions, but the low complexity and read-only annotation make this acceptable.

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 schema already describes the address parameter with 100% coverage, so the baseline is 3. The description adds the 'U.S.' qualifier, which is not present in the schema description, providing extra semantic constraint. This modest addition justifies a slightly higher score.

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 the tool's function with a specific verb ('look up') and resource ('elected representatives'), and specifies the input (U.S. address) and output scope (federal, state, local). This distinguishes it from siblings like get_voter_info or get_member, which focus on other aspects.

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 implies when to use the tool — when you need elected representatives for an address — but lacks explicit exclusions or comparisons to alternatives. It provides clear context without listing when-not-to-use scenarios, which is acceptable for a straightforward 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 declare readOnlyHint=true, and the description confirms read-only with 'List' and 'Returns a feed'. It adds some context about the feed being active stories grouping policies, but doesn't detail pagination or output structure. No contradiction.

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 no filler. Every sentence contributes to understanding the 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?

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, scope, and what is returned. It could mention explicit pagination or feed behavior, but overall it's complete for its simplicity.

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% with the 'limit' parameter described as 'Number of stories'. The description doesn't add extra parameter semantics, but with full schema coverage 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 uses the specific verb 'List' and identifies the resource as 'story bundles', adding scope with 'tracking ongoing policy issues' and 'active stories grouping related policies and developments'. This clearly distinguishes it from siblings like get_story (singular) and search_policies.

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 implies usage for viewing current, active story bundles related to ongoing policy issues. It doesn't explicitly state when not to use or name alternative tools, but the context is clear enough for an agent to differentiate from get_story.

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 declare readOnlyHint=true, so the agent knows it's a safe read operation. The description adds that the response includes the full timeline of related events, but it does not disclose error behaviors, prerequisites, or response format beyond that. This is acceptable but not rich.

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 a single well-structured sentence that front-loads the action ('Retrieve') and resource ('specific story bundle'), followed by what is included. No wasted words.

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?

The tool is simple with one parameter, a read-only annotation, and no output schema. The description states the purpose and key content (timeline of related events), which is sufficient for an agent to select and invoke the 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?

The schema describes bundle_id as 'Story bundle ID' with 100% coverage, so the schema carries the parameter meaning. The description doesn't add any additional parameter semantics such as format or constraints, making the baseline 3 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 clearly states the tool retrieves detailed information about a specific story bundle by ID, including the timeline of related events. This distinguishes it from sibling tool get_stories, which likely lists stories rather than retrieving a single one.

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 implies usage for fetching a single, specific story bundle by ID, contrasting with plural sibling get_stories. However, it does not explicitly mention when to use an alternative or provide exclusion criteria, so it falls short of a full guideline.

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 annotation readOnlyHint=true already declares this as a safe read operation. The description adds the detail that the address must be a 'registered U.S. voter address', which is a useful eligibility constraint but not a behavioral trait like side effects or error handling. No contradiction with 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?

The description is a single, front-loaded sentence that conveys the core purpose without extraneous words. Every piece of information (election info, polling location, early vote sites) adds 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?

For a simple read-only lookup tool with one parameter and no output schema, the description is sufficiently informative. It mentions the key return categories (upcoming elections, early vote sites) and the input constraint (registered U.S. voter address). It could be more explicit about failure modes (e.g., unregistered address), but the tool's simplicity keeps the gap small.

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% for the single parameter 'address', and the description restates it as 'registered U.S. voter address', adding minimal beyond the schema. The baseline of 3 is appropriate since the schema already documents the parameter adequately.

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 the tool's function: 'Get election and polling location information for a registered U.S. voter address'. It uses a specific verb ('Get') and resource ('election and polling location information'), and the scope ('for a registered U.S. voter address') distinguishes it from sibling tools like get_representatives or get_member.

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 implicitly conveys when to use the tool: when you need election or polling location data for a voter address. It does not explicitly mention alternatives or exclusions, but the context is clear enough. With a single parameter and read-only semantics, additional usage guidance is not critical.

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?

With readOnlyHint=true already covering safety, the description adds meaningful behavioral detail: it explains that resolution spans 'every bill that has carried it, through reintroductions and new Congresses,' which clarifies the tool's scope and aggregation behavior. It does not describe return format or edge cases, but given the read-only annotation and simple parameter, the added context is valuable and goes beyond the annotation.

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 a single, well-structured sentence that front-loads the user's question ('what is going on with policy X?') and immediately explains the resolution mechanics. Every word earns its place; no redundant or vague 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 the tool's low complexity (one parameter, no output schema), the description is largely complete: it explains what the tool does, what inputs it accepts, and the scope of the effort tracking. It does not explicitly state the return format or behavior on no-match, but the annotation and simple contract make this a minor gap rather than a critical omission.

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 schema already documents the 'name' parameter as a bill nickname, acronym, or media name. The description reinforces this with examples ('SAVE Act', 'big beautiful bill') and clarifies the intent, but it does not add substantially new semantic information beyond what the schema provides. Baseline 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?

The description clearly states the tool's purpose: resolving a bill nickname, acronym, or media name to an 'effort' that tracks a policy goal across bills and Congresses. It includes concrete examples ('SAVE Act', 'big beautiful bill') and distinguishes itself from siblings like get_effort by focusing on name-based resolution rather than direct retrieval.

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 opening phrase "Answer 'what is going on with policy X?'" gives clear usage context: use this when you have a colloquial name and want to understand the broader policy effort. It implies the primary alternative (get_effort for direct ID lookup) without explicitly naming siblings, and it sets expectations for cross-bill/cross-Congress tracking. It stops short of explicitly saying 'use X instead' but provides sufficient contextual 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 declare readOnlyHint=true, so the safe read nature is clear. The description adds 'current' scope and mentions it returns a list with key details, but does not disclose pagination behavior, response format beyond schema, or how partial matches are handled, leaving room for more transparency.

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 a single, front-loaded sentence that efficiently communicates the tool's purpose and primary filters. No wasted words or redundant 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?

As a search tool with optional parameters and no output schema, the description adequately conveys the core operation. However, it omits specifics about what 'key details' are returned and does not mention limit defaults or pagination, which would be useful for an agent to set expectations.

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 has a description. The tool description merely repeats the filter dimensions (name, state, party, chamber) without adding new meaning. Baseline 3 is appropriate as the schema does the heavy lifting.

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 the tool searches current U.S. Congress members by name, state, party, or chamber and returns a list. This distinguishes it from sibling tools like get_member, which likely fetches a specific member, by indicating a broad search capability.

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 implies when to use the tool (searching by criteria) but does not explicitly contrast it with alternatives such as get_member or get_representatives. There is no explicit when-not-to-use guidance, so usage context is only inferred.

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 annotation readOnlyHint=true already indicates a safe read operation, and the description is consistent. It adds that results are 'a list of matching policies with summaries,' which is useful output-shape context. However, it does not mention sorting, limiting, pagination, or error behavior, but the schema covers parameter defaults.

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 a single sentence that is concise and front-loaded with the verb and resource. It includes the key search facets and the return value in exactly 20 words, with no redundant phrasing. It earns its place without wasted words.

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 search tool, the description covers the purpose, search criteria, and return type. The schema handles parameter specifics, and the annotation covers read-only safety. No output schema exists, but the description addresses the return shape. Minor omissions like sort/limit behavior are already in the schema, so the description is sufficiently complete.

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 every parameter (query, sort, limit) is already documented with types, enums, defaults, and min/max. The description's mention of 'keyword, topic, or bill name' aligns with the query parameter but adds no new information. Given high schema coverage, 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 uses the specific verb 'Search' and clearly identifies the resource as 'U.S. federal policies and legislation,' with explicit search criteria (keyword, topic, bill name). It also states the return type (list of policies with summaries), making its purpose distinct from sibling get_* tools that retrieve individual entities.

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 implies when to use this tool—when searching by keyword, topic, or bill name—but does not explicitly mention alternatives or exclusions. For example, it does not say to use get_policy when a policy ID is already known, or get_policy_text for full text. The context is clear but lacks explicit differentiation from related tools.

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