Find US senior benefits by ZIP and check eligibility via deterministic rules citing .gov sources.
Scored across 3 tools
Each tool has a clearly distinct purpose: finding programs by ZIP, fetching details for a specific program, and running an eligibility scan. There is no meaningful overlap between them, and the descriptions make the boundaries obvious.
All tool names use snake_case with a clear verb_noun structure: find_programs_by_zip, get_program_details, and run_eligibility_scan. The naming pattern is consistent and predictable.
Three tools is appropriate for this focused domain: location-based discovery, program details, and eligibility assessment. Each tool serves a necessary step in the user journey without redundancy or bloat.
The tool surface covers the full read-only workflow: discover relevant programs, inspect details, and determine eligibility. Program IDs flow between tools, and the eligibility scan accepts optional fields to improve results, leaving no obvious dead ends.
List the federal, state, and county senior-benefit programs that apply where a person lives, from their 5-digit ZIP code. Each program includes its cited government source URL, a last-verified date, and an apply-guide link on discoverseniorbenefits.com. Optionally filter by jurisdiction level or category keyword.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | Yes | 5-digit US ZIP code. | |
| level | No | Only return programs at this jurisdiction level. | |
| category | No | Case-insensitive keyword matched against each program's category (e.g. 'food', 'property tax', 'utilities'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only and non-destructive, and the description adds useful behavioral and output context: each program includes a cited source URL, last-verified date, and apply-guide link. It does not contradict the annotaations and provides value beyond what the annotations alone 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?
Three tight sentences front-load the primary purpose, then cover output fields and optional filtering without wasted words. Every sentence earns its place by helping an agent select and invoke the tool correctly.
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 filtered list tool with read-only annotations, this description is largely complete: it covers the input, optional filters, and the key returned fields even without an output schema. It lacks explicit alternatives/error behavior and no-results handling, which keeps it just shy of perfect.
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?
Term: 3, schema description coverage is 100%, so the schema already fully documents zip, level, and category. The description adds a little extra semantic color around jurisdiction level and category keyword matching, but it does not substantially go beyond the schema's own descriptions.
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?
Clearly states the action (list) and resource (federal, state, and county senior-benefit programs) and the key input (ZIP). It implicitly contrasts with siblings such as get_program_details and run_eligibility_scan but does not explicitly name them, so it stops short of full sibling differentiation.
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 conveys the use case—when you have a ZIP code and need applicable programs—and mentions optional filters, so usage is inferable. However, it does not state when not to use this tool or explicitly route the agent to a sibling for details or eligibility scans.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full public details for one program by its id (ids come from find_programs_by_zip or run_eligibility_scan): description, cited government source, how to apply, documents required, and the apply-guide link on discoverseniorbenefits.com.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | 2-letter state code; resolves state-specific application channels for federal programs. | |
| program_id | Yes | Program id, e.g. 'fed.msp.qmb'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds useful behavioral context by listing the returned content and noting the program_id provenance. It does not go into error behavior or invalid-id handling, but for a simple read-only lookup the bar is met without being exceeded.
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 sentence that front-loads the core action and then uses a colon to list the return contents efficiently. Every phrase earns its place, and there is no redundant or filler wording.
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 low complexity (one required parameter, one optional), the annotations covering safety, and the description's explicit enumeration of return fields, nothing essential is missing. Even without an output schema, an agent can understand what the call returns and when to invoke it.
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 schema already documents both parameters. The description adds meaningful provenance context for program_id ('ids come from find_programs_by_zip or run_eligibility_scan'), but the state parameter is already well described in the schema. The baseline of 3 applies because the schema carries 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 states a specific verb ('get'), a specific resource ('one program by its id'), and clearly enumerates what will be returned (description, source, how to apply, documents, apply-guide link). It also distinguishes itself from the sibling tools by referencing them as sources of ids, making the tool's role 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 this tool: after find_programs_by_zip or run_eligibility_scan has produced a program_id. It names the alternatives directly and indicates their relationship to this tool. It stops short of explicitly stating 'do not use this for searching or eligibility scanning,' but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check which senior-benefit programs a person likely qualifies for, using a deterministic rule engine tied to cited .gov sources — no AI guessing. Only age and zip_code are required; every extra field provided turns needs-more-info programs into definite answers. Include marital_status whenever known — many programs' income limits depend on it, so it resolves far more programs than most fields. The full guided check at https://discoverseniorbenefits.com/scan covers additional signals.
| Name | Required | Description | Default |
|---|---|---|---|
| age | Yes | Age of the person the check is for. | |
| is_blind | No | ||
| zip_code | Yes | 5-digit US ZIP code. | |
| homeownership | No | ||
| is_us_citizen | No | ||
| household_size | No | ||
| marital_status | No | High-leverage: several income limits are set per single vs. couple, so those programs stay needs-more-info until this is provided. | |
| veteran_status | No | Whether the person, spouse, or deceased spouse served. | |
| wartime_service | No | 90+ days active duty with at least one day in a VA wartime period. | |
| disability_status | No | ||
| resources_estimate | No | Approximate countable savings/assets in dollars. | |
| va_disability_rating | No | VA disability rating (lower bound of the bucket). | |
| household_income_annual | No | Approximate annual household income in dollars. | |
| has_cognitive_impairment | No | Memory loss, dementia, or a cognitive condition affecting daily judgment. | |
| needs_personal_care_assistance | No | Needs regular help with daily activities (bathing, meals, mobility). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a safe read-only operation, and the description adds meaningful behavioral detail: deterministic rule engine, cited .gov sources, no AI guessing, and the extra-field resolution behavior. It does not describe output format in depth, but the behavioral disclosure goes well beyond what annotations provide.
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 compact and front-loaded: it opens with core purpose, then gives the minimal input contract, then highlights the most important optional parameter, and closes with a pointer to a broader check. Every sentence earns its place and there is no repetition of schema metadata.
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 15-parameter tool with no output schema, the description explains the main call contract, the role of optional fields, and the most impactful parameter. It could have described the response structure or explicitly named when to use sibling tools, but the given context is enough 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?
With 67% schema description coverage, the schema already documents most parameters. The description reinforces the two required fields and adds substantial guidance about marital_status, explaining why it is high-leverage and how it affects program resolution. That is real value beyond the input 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 that the tool checks which senior-benefit programs a person likely qualifies for, using a deterministic rule engine. It does not explicitly contrast with sibling tools like find_programs_by_zip or get_program_details, but the resource and action are specific enough to distinguish it.
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 provides useful invocation guidance: only age and zip_code are required, extra fields convert needs-more-info programs into definite answers, and marital_status is high-value. However, it never explicitly says when to prefer this tool over the sibling tools, so agent routing relies mostly on the tool names and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sourced, dated US home-energy program truth by ZIP.
Find evidence-backed U.S. free trials and savings; public benefits are available by explicit scope.
US ZIP code intelligence: demographics, weather, tax, crime, housing, voting, and more.
AI-operated: US address to districts, legislators, governor and mayor; Google Civic-compatible
