Offendersearch

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

With no annotations, the description fully discloses behavior: row-by-row engine equivalence, error handling (status='error', never aborts batch), max rows, return format, and the crucial caveat about sourcesIncomplete meaning 'lower bound'. It also documents authentication via X-API-Key or env var. This is rich, transparent context.

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 densely informative without fluff. The first sentence captures the core function, then proceeds logically: behavior, return format, caveat, auth. The use of bullets and the star-marked warning keep critical caveats prominent. Every sentence earns its place despite length.

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 6-parameter tool with no output schema, the description covers all essential aspects: the input query format, return structure with counts and errors, error semantics, the lower-bound warning, authentication, and a pointer to search_offenders for shared parameter meanings. An agent can invoke it correctly and interpret results accurately.

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%, but the description adds significant semantic value: explains 'queries' as row-in/row-out with input order, enumerates allowed fields, and outlines result structure. It also interprets match/freshness/jurisdictions by referencing search_offenders for context. This goes well beyond the schema text.

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?

Description opens with 'Run many person/lookup lookups in one call (row-in / row-out)', clearly stating the tool's verb, resource, and batching behavior. It explicitly distinguishes from siblings by noting 'same engine as search_offenders', making its niche 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 implies use for multiple lookups ('many... in one call') and references search_offenders as the single-query alternative, but does not explicitly say 'use this instead of search_offenders when you have multiple queries'. It provides constraints (max 1000 rows) but not a direct usage contrast.

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 no annotations, the description carries the behavioral burden, and it does so well: it reveals that the data is dynamic ('currently answering'), that coverage depth varies, and that a state with many county jurisdictions is not necessarily better covered. It stops short of mentioning refresh behavior or operational constraints like rate limits, but for a zero-parameter listing tool the key traits are covered.

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 three short paragraphs, each earning its place: one states the core action, one gives usage context and an interpretive caveat, and one clarifies the return contents. It is front-loaded and avoids filler or restatement.

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 zero-parameter tool with no output schema, the description is nearly complete: it explains what is returned, how to use the result, and how to interpret an important data-quality nuance. It does not explicitly contrast with the similar-sounding get_registry_coverage sibling, which would have made the tool boundary fully unambiguous.

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 tool has zero parameters, so there is little to add beyond the baseline. The description still enriches the output semantics by explaining what each jurisdiction entry will contain—code, state, kind, and status—giving an agent a mental model even without schema-provided parameter docs.

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 opens with a specific verb and resource: 'List the criminal-record jurisdictions searched, with kind and status.' It clearly distinguishes the tool's coverage-mapping purpose from the sibling search tools, which focus on queries rather than jurisdiction availability.

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?

It gives explicit guidance to use this tool 'before relying on an empty result,' which tells an agent when the tool matters. It also explains how to interpret uneven coverage, but it does not explicitly name alternatives or state when not to use this tool versus get_registry_coverage or the search tools.

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 no annotations provided, the description carries the full behavioral disclosure burden. It thoroughly explains the return shape, the meaning of each SourceInfo field, and the crucial semantic distinction that health fields are operational metadata, not search-quality indicators. It also states that no API key is required.

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 longer than average, but every section earns its place: a one-sentence purpose, a structured return field listing, and a critical behavioral warning that prevents misinterpretation. The most important caveat about health fields is clearly separated and emphasized.

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 no-parameter tool with no output schema, the description is exceptionally complete. It covers the purpose, use cases, return contract, field enums, and operational semantics, including exactly what the health fields should and should not be used for. Nothing essential 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?

The input schema has zero parameters and 100% schema coverage, so there is no parameter semantics burden for the description. The description adds no parameter-level meaning, but none is needed. Baseline 4 for a no-parameter tool 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: 'List every registry we cover plus its scope, legal status, and health.' This clearly identifies what the tool does. However, it does not explicitly distinguish itself from the sibling tool get_criminal_coverage, relying on name similarity rather than an explicit 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 provides explicit when-to-use guidance: discover jurisdiction codes accepted by search_offenders/batch_search and check per-registry freshness/health. It also gives a strong 'do not' instruction against interpreting health fields as search-quality warnings, which is essential for correct use.

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 no annotations, the description assumes the full disclosure burden and does it well: it defines what each recordType implies, warns that bookings are not convictions, that warrants mean 'SOUGHT', and attaches FCRA restrictions. It even instructs the agent to read recordType before characterizing anyone. This is far beyond the minimum.

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 long but front-loaded with the core purpose and organized into readable paragraphs; the surname/recordType/FCRA guidance is all substantive. A few phrases, like the federal-layer explanation, are useful context rather than waste.

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 no output schema, it documents the returned record fields (name, aliases, dob, sex, race, state, county, custody, sentence, cases, sources, matchConfidence/matchBasis) and the pagination counts. It covers search behavior, caveats, and legal constraints, leaving the agent enough to invoke 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?

Input schema already describes all 8 parameters, so baseline is 3; the description adds real value by explaining that surname is non-optional, that firstName + DOB or birthYear strengthen matching, and that a common surname yields thousands of results. It also calls DOB 'the single strongest disambiguator,' which is not 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?

Opens with a clear verb and resource: "Search US criminal records" and enumerates county jail bookings, prison custody, court cases, and warrants. Scope is unambiguous, but it never explicitly distinguishes itself from the sibling search_offenders or tells the agent which searches are excluded, so sibling differentiation is absent.

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?

It gives explicit invocation guidance — 'A surname is REQUIRED' and advises supplying firstName plus DOB/birth year 'wherever you have them' — and explains why (bare common surnames return thousands). It doesn't state when to prefer a sibling tool like search_offenders, so no exclusions/alternatives are 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 no annotations provided, the description carries the full burden of behavioral disclosure and meets it thoroughly. It reveals that results may be partial, that counts.sourcesIncomplete makes records a lower bound, that warnings are always present, and that registries can fail without invalidating the search. It also exposes the auth mechanism and the difference between light and extensive calls.

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 long but well-organized: a one-line summary, then fan-out behavior, a clear warning section, a structured return-field list, and an auth note. Critical operational guidance (read sourcesIncomplete before reporting) is highlighted early and in plain language. Every section earns its place given the 18-parameter surface and absence of an output schema.

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 complex 18-parameter read tool with no output schema, the description is remarkably complete. It documents the response structure, per-source status fields, cache tiers, geo-search behavior, jurisdiction control, and the crucial lower-bound caveat. An agent has enough context to call it correctly and interpret its results without additional documentation.

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 is 3, but the description adds substantial meaning beyond field names and types. It clarifies subtle behaviors such as `state` being a residence filter that does not change which registries run, `location_scoped` being an opt-in recall-reducing knob, `match` levels affecting fuzzy tolerance, and `deadline_ms` causing partial results. This materially improves an agent's ability to choose correct parameter combinations.

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 opens with a specific verb and resource: 'Search US sex-offender registries for one person and/or location.' It goes beyond a vague summary by explaining the fan-out, de-duplication, scoring, and normalized record output. The resource is clearly distinct from siblings like search_criminal at a glance.

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 gives clear guidance on when to call the tool: when searching sex-offender registries, and it explains what identifiers to supply ('at least a name, location, or free-text q should be given'). It also references get_registry_coverage for registry codes, pointing the agent to the right companion tool. It does not explicitly contrast with search_criminal or batch_search, but the resource scope makes the primary context clear.

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