get_lists_by_id_items_show

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds some behavioral detail, like the allowed values for 'watchnow' and pagination parameters, but does not disclose other behavior such as default sorting, response format, or edge cases. It provides minimal extra context beyond the annotations.

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 structured as a parameter list, which is organized but verbose. The opening sentence is concise, but the parameter list repeats the endpoint and includes many terse entries. It is not excessively long, but could be more compact and front-load the most important usage details.

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 19 parameters, an output schema, and no schema descriptions, the tool needs thorough parameter documentation. The description fails to specify formats for many filters (e.g., 'years', 'genres', 'ratings') and does not explain the interaction between filters or pagination defaults. An agent would struggle to construct correct requests for most optional parameters, making this incomplete for a tool of this complexity.

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 must compensate, and it does list all parameters with brief explanations. However, many are just 'Query parameter' without format or allowed values, which is unhelpful. The 'watchnow' parameter gets detailed enumeration, and 'id', 'extended', 'sort_by', 'sort_how', 'page', 'limit', and the ignore_* flags have some clarification. Overall, it adds some meaning but not enough for all parameters.

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 action: 'Get show list items' and includes the endpoint path, which specifies the resource. It is distinct from sibling tools like get_lists_by_id_items_movie by the type 'show', so an agent can infer the scope. However, it doesn't explicitly contrast with the generic get_lists_by_id_items_by_type tool, so it slightly lacks differentiation.

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?

There is no guidance on when to use this tool instead of alternatives such as get_lists_by_id_items_movie or get_lists_by_id_items_by_type_by_sort_by_by_sort_how. The description only lists parameters without explaining the intended use case or exclusions. An agent would have to infer from the name that this is for show items specifically.

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