ImmigrationLayer

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

Annotations already establish a safe read-only, closed-world operation, and the description adds substantial context beyond them: no sign-in, a 20-calls-per-minute-per-IP limit with a rate_limited response, the not_found path for unsupported forms, the announced_edition field for a future edition not yet accepted, and source attribution to uscis.gov or a dated web.archive.org capture. That is exactly the behavioral texture annotations cannot 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?

Front-loaded with the return value, then usage, sibling routing, coverage, access terms, limits, and provenance. Every sentence carries operational information, though the tail end ("Not legal advice" plus source attribution) adds length after the key facts are already delivered.

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?

An output schema exists, so return-value structure needn't be explained, and the description covers the remaining risks: valid versus invalid inputs, the announced_edition edge case, rate limiting, and source provenance. Nothing an agent needs in order to call this correctly is missing.

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% and the schema already specifies the exact uppercase hyphenated format with a counterexample. The description still adds value by enumerating which form identifiers are actually valid, converting the string parameter into an implicit enum and telling the agent what happens outside it.

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?

States a specific verb and resource up front: returns the currently accepted edition of one USCIS form plus its accept-from and reject-from dates. It also distinguishes the sibling list_form_changes by scope (single form vs. all forms since a date), so an agent can route correctly 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.

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

Explicitly says when to use it ("check which edition of a form USCIS accepts, with the date of that answer") and names the alternative with its triggering condition ("For edition changes across all forms since a date, use list_form_changes"). It further bounds applicability by listing the nine supported forms and stating any other form returns not_found.

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?

Adds substantial behavior beyond the read-only annotations: sign-in and active-plan requirements, subscription_required and rate_limited errors, 30-calls-per-minute limit, not_found/no-fee outcomes, amount semantics, and filing-channel unspecified behavior. These details are directly useful to an agent invoking the tool.

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 purpose is front-loaded, but the description is very long and dense, with repeated parameter guidance and extensive source citations. It is complete yet not concise.

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 multi-country fee lookup complexity, the description covers coverage limits, required category conditions, error behavior, authentication, rate limits, and source context. An output schema exists, so return-value details need not be fully elaborated.

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 the schema already carries the parameter semantics. The description largely repeats the form, filing, country, and category rules rather than adding much beyond the structured fields.

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?

States a specific verb and resource: returns a published government fee and effective date, with clear US/GB/AU coverage. It distinguishes itself from check_form_edition by directing current-edition lookups there.

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?

Provides explicit usage context by country, notes that it does not determine which fee applies to a case, and names check_form_edition as the alternative for current editions. It also explains fallback behavior for uncovered categories and unsupported forms.

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?

Goes well past the readOnly/openWorld annotations: discloses auth requirements (sign-in plus active plan), the exact failure codes (not_found, subscription_required, rate_limited), a concrete rate limit (30 calls/min shared across all paid tools), and that omitting category or office for US yields not_found. It also names source provenance and licensing, which matters for how the numbers should be cited.

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?

Purpose is front-loaded and the country-by-country structure is scannable, but the text is long and repeats 'It does not say how long a given application will take' three times. The trailing licensing paragraphs are necessary for attribution yet consume a large share of an already bloated description.

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?

Output schema exists, so return values need not be explained. For a multi-country, multi-source lookup with auth gating and rate limits, the description covers everything an agent needs to call it correctly and interpret failures.

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 the per-country meaning of form/office/category is already fully documented — most of the description's parameter text duplicates it. It does add two things the schema does not: the not_found consequence of omitting category or office for US, and the fact that footnote data surfaces as category_notes. Useful but marginal over an already-complete schema, so baseline 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?

States a specific verb and resource ('Returns a published processing time for one form or visa route, category, and office') and immediately breaks it down per-country source (USCIS, UKVI, Home Affairs). It explicitly routes to a sibling ('For Visa Bulletin waits, use get_visa_bulletin'), so an agent can separate this from get_visa_bulletin and get_fee without opening a schema.

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?

Gives an explicit trigger ('Use it when the user asks for USCIS's published processing time for a form'), an explicit exclusion ('It reports past completions, not how long a given case will take'), a named alternative for the adjacent need, and per-country conditions that determine what to pass. Nothing about when-to-call is left to inference.

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 readOnly/openWorld=false/destructive=false, and the description adds substantial context beyond them: sign-in requirement, plan gating, the subscription_required and not_found and rate_limited error paths, a 30/min shared rate limit, and the data source. This is exactly the behavioral detail an agent needs before calling.

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?

Front-loaded with purpose and trigger, then alternatives, then error/auth/rate-limit facts. Dense but every sentence carries operational value; only the trailing 'Not legal advice' and source line are marginally expendable.

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 4-required-param lookup with an output schema, the description covers the trigger, the sibling alternatives, the value encoding of the returned cutoff, and all failure modes (not_found, subscription_required, rate_limited). Nothing an agent needs to call it correctly is missing.

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% and each parameter already carries an enum or exact-value description, so the schema does the heavy lifting. The description's extra detail (the 'C'/'U'/'YYYY-MM-DD' cutoff values) describes the returned field rather than the inputs, so it adds little to parameter semantics beyond the schema. 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?

States a specific verb and resource ('Returns one family- or employment-based cutoff from a month's State Department Visa Bulletin') and names the exact dimensions (chart type, category, country). It explicitly distinguishes itself from get_visa_bulletin_dv and get_visa_bulletin_notes, so an agent can route correctly without opening schemas.

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?

Gives an explicit trigger ('Use it when the user asks whether a priority date is current') and names two alternatives with the conditions that select them (DV lottery cutoffs, advisory notes). Nothing is left to inference.

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?

Goes well beyond the annotations by disclosing error semantics (a month or region not on file returns not_found), auth and cost ('free, no sign-in required'), and a concrete rate limit ('20 calls per minute per IP, then rate_limited'), plus the data source and a legal disclaimer. The annotations already carry the read-only/closed-world profile, so this is a genuinely additive disclosure; the only missing piece is whether the cutoff is a rank number versus a date field, which the output schema presumably covers.

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?

Five short sentences, front-loaded with the core behavior, then the routing to siblings, then failure mode, then operational facts. Every sentence carries distinct information; none repeats the schema or annotations.

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?

With an output schema present, return values need no explanation, and the description still covers failure modes, rate limits, cost, and data provenance. The only gap is that it does not say whether a missing country exception falls back silently or is flagged, though the schema hints at the fallback.

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 month format, the exact region list, and the country fallback behavior are already documented in the schema. The description's phrase about a 'country exception the bulletin lists within that region' reinforces the country parameter's semantics but adds little beyond what the schema states. 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?

States a specific verb and resource: returns the Diversity Visa rank cutoff for one region in a given month's bulletin, plus any country exception listed within that region. This is clearly separable from get_visa_bulletin (family/employment chart dates) and get_visa_bulletin_notes (advisory notes) 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.

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

Gives the triggering scenario explicitly ('use it when a DV selectee asks whether their case number is current') and names both alternatives with the conditions that select them. Nothing is left to inference about when this is the wrong 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 a safe read-only, closed-world operation, and the description adds substantial context beyond them: empty-list vs not_found semantics, no auth or cost, a concrete rate limit (20/min per IP) with the resulting rate_limited error, and a data source. This is exactly the extra behavioral detail the agent cannot infer from 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 purpose and the routing guidance are front-loaded, and the trailing sentences each deliver a distinct operational fact (empty vs not_found, cost/auth, rate limit, disclaimer, source). No sentence is filler despite the density.

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?

An output schema exists, so return-value shape needn't be documented, and the description still covers the two edge outcomes an agent must handle (empty list vs not_found). Combined with the rate-limit and auth notes, nothing needed to call this tool correctly is missing.

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% and the single 'month' parameter already carries the YYYY-MM pattern, an example, and the not_found caveat. The description restates the not_found behavior but adds no new syntax or format meaning, so the baseline 3 for schema-complete parameters 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?

Opens with a specific verb and resource ('Returns every lettered advisory note in a month's Visa Bulletin') and immediately illustrates the content with a concrete example ('EB-1 India may become unavailable'). It explicitly distinguishes itself from the sibling chart tools get_visa_bulletin and get_visa_bulletin_dv.

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?

Gives an explicit trigger ('when the user asks whether dates are expected to advance, hold, or retrogress') and names the alternatives plus the condition that selects them ('For the chart dates themselves, use get_visa_bulletin or get_visa_bulletin_dv'). Both when-to-use and when-not-to-use are covered.

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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial context beyond them: 100-item-per-resource page caps, cursor continuation rules, the meaning of empty first-page lists, free/no-sign-in access, and a concrete 20-calls-per-minute-per-IP limit with the rate_limited failure mode. Source provenance and the per-item source URL/content hash round it out.

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?

Front-loaded with purpose and alternatives, and nearly every sentence carries operative information. The trailing provenance sentences about source URLs and content hashes are useful for verification but push the length near the limit for a two-parameter read 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?

With an output schema present, return shape need not be explained. The description still covers pagination, rate limits, access cost, empty-result semantics, and data provenance — nothing an agent needs to call this correctly is missing.

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 baseline would be 3, but the description adds real semantics: cursor must be passed as next_cursor with the same since value and paginated until next_cursor is null. That is a non-obvious usage constraint not visible in 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 first sentence names a specific verb and two concrete resources (form edition changes plus USCIS newsroom and Federal Register alerts), states the ordering (newest first) and the scope (edition changes are exactly those check_form_edition covers). This distinguishes it clearly from check_form_edition and search_alerts 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.

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

Explicitly states the use case ("catch up on what changed since a last check") and routes to both alternatives with their selecting conditions: check_form_edition for one form's current edition, search_alerts for keyword lookup. Both when-to-use and when-not-to-use are present.

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 cover the read-only, closed-world, non-destructive profile, and the description goes well beyond them: sign-in and active-plan requirements, subscription_required failure mode, 30 calls/minute shared rate limit with rate_limited signal, 100-match page cap with next_cursor paging, and empty list rather than error. It stops short of describing result field shape, but an output schema exists to cover that.

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?

Front-loaded and well organized by country, but bloated: the source list appears twice (inline per country and again in an explicit "Sources:" sentence), and provenance/licence paragraphs plus a disclaimer crowd out the operational content. Roughly a third of the text could be cut without losing decision-relevant 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?

For a multi-corpus search tool with a full output schema and complete annotations, everything an agent needs to call it correctly is present: required keyword, country behavior, pagination loop termination, auth and rate-limit failure modes, and the sibling alternative for date-only listing.

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 all four parameters. The description still adds real semantics the schema lacks — country-dependent corpora, title-only matching for GB, the default of US, and the fact that summaries are not searched. Slight deduction because cursor/since behavior is largely left to 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?

States a specific verb and resource (searches published immigration announcements), the ordering (newest first), and enumerates exactly what corpus is searched per country (USCIS newsroom + Federal Register; Home Office media feed; Migration Regulations compilations). An agent can distinguish this from check_form_edition or get_fee purely from the text.

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?

Gives a concrete usage example ("I-765" or "fee") and explicitly routes the no-keyword-by-date case to list_form_changes, even noting that alternative is free. It also warns that AU titles only carry compilation numbers and that searching "compilation" is the way to list them.

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