Download history

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

readOnlyHint=true is consistent with a history read. Beyond annotations it discloses genuinely useful behaviour: results are merged across many backends into one vocabulary with the upstream word kept in `rawEvent`, failures carry the download client's own message, and deleting a title also destroys its Radarr/Sonarr history. It stops short of describing pagination stability or response shape (offset warns items can move between pages only via the schema).

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?

Front-loaded with the core definition, then escalation to the failure-diagnosis use case and the deletion caveat. Dense but nearly every clause carries new information; the parenthetical service inventory is long but earns its place by signalling coverage breadth.

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?

An output schema exists, so return values need no explanation, and the description covers sources, scoping, and the history-loss caveat. Minor gap: it doesn't state whether merged multi-service results can fail partially or how `detail` levels differ, though the schema covers the latter.

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 coverage is 100%, so the baseline is 3; the description still adds cross-tool meaning by tying `service`+`id` to a single movie/series/artist and by linking the returned `downloadId` to an *arr grab and to trigger_scan's postprocess action. It also points to arr://docs/get_history for the field reference rather than duplicating it.

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?

States a specific scope: 'What happened to a download after it left the queue (grabbed, imported, failed, deleted), merged across the *arrs, SABnzbd, NZBGet...'. It enumerates the normalised event vocabulary and names the sibling it differs from (get_queue), so an agent can pick it without opening 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?

Explicit when-to-use with the motivating question ('why did last night's download fail') and the exclusion ('get_queue cannot see finished or failed items'). It also gives conditional routing: pass `service` and `id` to scope to one title, and use `source: "webhooks"` when a title was deleted and its *arr history is gone.

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