sonarr_get_series

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

With no annotations, the description carries the burden and adds value by disclosing that only summary fields are returned, preventing the agent from expecting full detail. It also explains the rationale behind the default limit, which is behavioral context. It does not mention read-only status explicitly, but the 'get' verb implies a safe read operation.

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, each serving a distinct purpose: stating the tool's function and providing behavioral/usage context. There is no redundant content or excessive detail.

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 simple list endpoint with three optional parameters and no output schema, the description gives enough context: what it retrieves, the summary-only nature, the default limit, and the search-before-pagination guidance. It could mention read-only safety or return field specifics, but these are not critical for invoking the tool correctly. Overall, it is sufficiently complete.

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 already covers all three parameters with full descriptions, so the baseline is 3. The description adds a small hint about using 'search' early for filtering, but does not elaborate on offset or limit format beyond the schema. Overall, it does not significantly enhance parameter understanding beyond structured data.

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 'Get TV series from the Sonarr library' with a specific verb and resource. It distinguishes from other tools by noting 'Returns summary fields only' and referencing 'search' for filtering, setting it apart from episode or search tools.

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 advises 'use search to filter before paginating', providing explicit guidance on ordering operations. It also explains that the default limit is intentionally set to 25 to keep context usage low, which helps the agent decide whether to adjust pagination. However, it does not explicitly name alternative sibling tools or exclusion criteria.

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