Find resources by name

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

Annotations already declare readOnlyHint=true, so the description correctly implies no side effects. It adds behavioral details beyond the annotation: case-insensitive substring matching, exact-id support, default non-admin kinds, and the effect of `kinds` to include admin kinds. These are useful runtime behaviors not captured by structured metadata.

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 concise and front-loaded with the core purpose, then packs matching behavior, defaults, and filtering into a logically structured sentence. It avoids redundancy with schema descriptions and uses compact phrasing. Slightly dense but not verbose; every sentence earns its place.

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 complexity (multiple kinds, filters, pagination via offset/limit), the description covers key usage aspects: matching semantics, defaults, and filtering. The output schema exists, so return values don't need explanation. It lacks explicit mention of pagination behavior, but that is documented in the schema (offset/limit parameters). Satisfactory for a search tool.

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 has 100% description coverage, so the baseline is 3. The description adds value by explaining the default behavior of `kinds` (all non-admin kinds) and how to include admin kinds, which is not explicit in the schema. It also clarifies that `query` can be a substring or exact id. This enriches parameter meaning beyond the raw schema definitions.

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 searches records across resource kinds by name/title, with a specific verb ('Search records') and resource scope ('across resource kinds'). It distinguishes from siblings like get_resource (which fetches a specific resource) and list_resource (which lists whole collections) by explicitly mentioning the search capability and avoiding full client-side listing.

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 context on when to use it: for finding records by name without listing whole collections, which implies it's preferred over list_resource for name lookups. It also explains defaults and how to narrow with `kinds` and `tag`, but does not explicitly state when *not* to use it (e.g., when you need exact resource retrieval via get_resource). The guidance is implicit rather than explicit exclusions.

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