get_discover_tv_language_by_language

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the HTTP method and path, which is technical, not behavioral. It does not disclose pagination behavior, rate limits, or any quirks about the language parameter (e.g., accepted formats). No additional behavioral context is provided.

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 short, but the first sentence is the only substantive content. The 'Args:' section merely repeats parameter names and types already present in the input schema, adding no value. This is wasted space that does not 'earn its place.' The structure front-loads the purpose, but the redundant parameter listing undermines conciseness by diluting the description with low-value information.

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?

With three parameters, zero schema description coverage, and only an output schema (which handles return structure), the description must explain the inputs and usage context. It does not. The meaning of 'language_query' is ambiguous, pagination behavior is unaddressed, and there is no guidance on how to construct a valid request. The description is insufficient for an agent to correctly invoke the tool without additional assumptions.

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 by explaining the parameters. It merely lists them: 'language: Path parameter. page: Query parameter. language_query: Query parameter.' This adds no semantic meaning beyond the schema. It does not explain what language_query does, whether page is 0-indexed, or how language is formatted (e.g., ISO 639-1). The description fails to bridge the gap left by the missing schema descriptions.

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 states 'Discover TV shows by original language', which clearly identifies the verb (discover), the resource (TV shows), and the filter (original language). It differentiates from siblings like get_discover_tv_genre_by_genre_id or get_discover_movies_language_by_language. However, it does not clarify whether 'language' refers to an ISO code, name, or other identifier, and it does not mention what the response contains. Still, the core purpose is clear and non-tautological.

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?

The description provides no guidance on when to use this tool versus alternatives. It does not mention that it is for TV-only discovery, that it filters by original language, or that movie equivalent exists. There is no mention of when to prefer this over get_discover_movies_language_by_language or other discover tools. The user must infer usage from the name and endpoint.

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