sound_search

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

With no annotations, the description carries the full burden of behavioral disclosure. It does reveal that results include 'caller assessments' and 'currently registered instrument availability', which are specific behavioral aspects. However, it does not state whether the operation is read-only, requires authentication, or has any side effects. For a search tool this is likely read-only, but that is not explicitly disclosed.

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 a single, tightly written sentence with no filler. It front-loads the core action and resource. It earns its place with no redundancy.

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 search tool with no output schema, no annotations, and only two parameters, the description is too thin. It does not describe the return format, how to structure queries, what limit means, or how this search differs from siblings. The agent has no information to make an informed call about parameter values or interpretation of results.

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 0%, so the description must compensate, but it does not explain how 'query' or 'limit' are used. The description only hints at what the search returns, not what the parameters control. An agent would not know whether 'query' is a free-text search, a filter on assessments, or something else. This is a significant gap given no other documentation.

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 uses a clear verb 'Find' with a specific resource 'sound records' and includes distinctive criteria ('caller assessments' and 'currently registered instrument availability'). This distinguishes it from sibling tools like effect_search and catalog_search, though it could be more explicit about what 'caller assessments' means. The purpose is understandable without needing to inspect the 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?

The description gives no guidance on when to use this tool versus the many sibling search tools (effect_search, catalog_search, content_search, etc.). There is no mention of when this is appropriate, what kinds of queries it best handles, or when to prefer another tool. An agent would have to guess based on the name and brief description.

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