arr_call

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

With no annotations the description carries the full burden and does so: it discloses that API roots are injected per service, that Plex /accounts is blocked, that Plex responses are forced to JSON, that Tdarr read modes via /cruddb run immediately while other modes need confirmation, and that changes are staged until confirm=true. The confirm_phrase format and example, plus 'never guess a body: read with GET first', are exactly the behavioral context an agent needs.

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?

Purpose is front-loaded in the opening line and the rest is dense per-parameter and per-service reference material with almost no filler. It reads as fragmented schema-style fragments rather than prose, and the confirm rules are split across two paragraphs, but nothing is genuinely wasteful.

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 complex, unannotated 8-parameter passthrough this is close to sufficient: service routing, auth-adjacent safety, and service quirks are all covered, and an output schema exists so return values need not be explained. Gaps remain around max_chars truncation behavior and what happens on API errors or partial failures.

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 0%, so the description must compensate, and it does for seven of eight parameters: service values, path format and query-string prohibition, allowed methods, params semantics (including qBittorrent form fields), body usage limits, confirm, and confirm_phrase. The exception is max_chars, which is never mentioned despite controlling output truncation.

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 verb and resource ('Call any API path on a service') and enumerates the exact service set plus example paths, so an agent knows this is a raw API passthrough. It does not, however, contrast itself with the many purpose-built siblings (arr_search, arr_add, arr_queue, plex_libraries), which an agent may pick first.

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?

Gives clear conditional context: GET runs immediately, mutations require confirm=true and user approval, and destructive operations additionally require a formatted confirm_phrase with a worked example. It stops short of saying when to prefer a dedicated sibling tool over this escape hatch, so the alternative-selection guidance is incomplete.

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