list_movies

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the HTTP GET method and paging parameters, which are consistent with a read operation. However, it does not disclose potential defaults for start/length or any filtering behavior beyond radarrid.

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 brief and front-loaded with the main purpose. The endpoint and parameter list follow logically. No filler exists, though the format is fragmented. It earns its keep without being verbose.

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?

Given the output schema covers return values and annotations cover safety, the main gaps are usage differentiation and nuanced parameter semantics. For a simple list endpoint, this is adequate but not complete: an agent might not know the default paging values or whether radarrid is required. The presence of many sibling list tools makes the lack of usage guidance more consequential.

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. It provides minimal one-line explanations for start, length, and radarrid. This is helpful but thin: start/length are explained as paging integers, and radarrid as 'Movies IDs,' though it does not explicitly state that radarrid is an array or how paging bounds work.

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 a verb and resource: 'List movies metadata.' It also signals that it targets specific movies, which distinguishes it from broader list tools, but it does not explicitly differentiate from siblings like list_movies_blacklist or list_movies_history. The GET endpoint is included, reinforcing purpose.

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?

No guidance is provided about when to use this tool over alternatives. There is no mention of when to prefer list_movies vs list_movies_wanted, list_movies_blacklist, etc., and no exclusions or conditions. The description only states what it does, not when to use it.

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