sonarr_search_releases

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

The description explicitly discloses that this is a write operation that modifies the Sonarr instance, which aligns with annotations readOnlyHint:false and adds a clear warning. It also hints at parameter usage ('body carries seriesId/episodeId'), providing context beyond the annotations. However, it doesn't detail side effects like triggering indexer searches or creating history entries, which would be richer transparency.

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 two sentences with no filler. The first sentence states the action and the second adds a crucial warning. It is front-loaded and every word 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?

The description covers the core purpose and the write nature, but for a tool that triggers a search and modifies state, it would benefit from more detail about request requirements (e.g., which of seriesId/episodeId is required) and potential side effects. The output schema exists to explain returns, so that's not a gap, but the parameter semantics are under-specified.

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?

With schema description coverage at 0%, the description compensates partially by naming key fields: 'seriesId/episodeId'. This is valuable for a generic 'body' object with additionalProperties:true. However, it leaves 'other options' undefined and doesn't specify whether seriesId or episodeId is required, so the semantics are incomplete but useful.

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's purpose: 'Search for releases for a series/episode'. It identifies the resource (releases) and the scope (series/episode). While it doesn't explicitly contrast with sibling tools like sonarr_list_release, the verb 'search' distinguishes it from 'list' and 'push' operations, making the purpose clear.

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 no explicit guidance on when to use this tool versus alternatives. It implies usage through the purpose statement, but does not mention excluding cases or alternative tools. The write warning is a caution, not a usage guideline.

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