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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, and the description reinforces this ('a read: it only searches') while adding real value: a scale warning (millions of records), the non-snapshotted pagination caveat, and the POST endpoint mapping. The main remaining gap is return shape and pagination totals, but overall this goes meaningfully beyond 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?

Five short sentences, front-loaded with the resource, then filters, then the scaling constraint, then the pagination caveat and the sibling pointer. No filler; each sentence carries a distinct operational instruction.

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 19-parameter, no-required, no-output-schema search tool, the description covers scope, returned headers, narrowing strategy, pagination stability and the field-values alternative, which is enough to call it correctly. Minor incompleteness: no mention of paging limits (max page 100000, page_rows 500) beyond the schema, and no guidance on result totals.

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 baseline is 3; the description goes further by grouping the filter families ('date range, form, location, resource, identifier and compliance') and stating the mandatory narrowing strategy. It does not explain individual parameters like time_zone_offset or date_type, but those are already documented 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 specific verb+resource ('Search submitted records') and immediately enumerates the header fields returned (record number, compliance, submitted date, location, form/version, resource, submitter, signed, verifications, ids). It also names the sibling it does not return field values for (safetychain_get_record_fields), so an agent can distinguish it from get_record/get_record_fields 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 hard usage rules: 'Always narrow by a date range or a name: the tenant can hold millions of records', and routes field-value retrieval to safetychain_get_record_fields. It also supplies a when-to-do-what condition for pagination ('for a stable multi-page read use a closed date range'), which is exactly the kind of alternative/exclusion guidance that prevents misuse.

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