resolve_effortAnswer "what is going on with policy X?" — resolve a bill nickname, acronym, or media name ("SAVE Act", "big beautiful bill") to the effort tracking that policy goal across every bill that has carried it, through reintroductions and new Congresses.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | A name for the effort: bill nickname, acronym, or media name (e.g. "SAVE Act", "big beautiful bill") |
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.
Add one secure layer between your agents and this server.
Each tool targets a distinct resource or action: efforts, members, policies, stories, representatives, voter info, and text retrieval. Even similar tools like get_effort and resolve_effort clearly differ in input type (ID vs natural language), and get_stories vs get_story follow the standard list/detail distinction.
All tool names follow a consistent verb_noun pattern using lower_snake_case: get_ for retrieval, search_ for queries, and resolve_ for name resolution. Nouns are clear and descriptive, with no mixing of styles or inconsistent verbs.
With 12 tools, the set is well-scoped for a U.S. political policy tracking service. Each tool provides a distinct utility without overwhelming the surface, fitting solidly within the expected range.
The tool surface covers the core read-only workflows: searching and retrieving policies and members, resolving and retrieving efforts, listing and retrieving story bundles, and looking up representatives and voter info. There are no obvious gaps or dead ends for the stated purpose.