get_aliases

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

No annotations are provided, so the description carries the full burden. It describes the tool as a read operation, but lacks details on potential errors, authentication requirements, or limits (e.g., pagination). The presence of an output schema may partially compensate, but the description itself does not disclose behavioral traits beyond reading.

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 concise with three sentences: one explaining the purpose, one defining the concept, and one directing to create_alias. It also includes a clear parameter list. No wasted words.

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 existence of an output schema, the description adequately covers the tool's purpose, parameters, and relationship to sibling tools. It lacks details on error handling or prerequisites, but for a read-only list tool, it is reasonably complete.

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 0% schema description coverage, the description adds meaning by explaining each parameter: series_slug is 'Series slug (e.g. "tvdb1234")' and season is 'Optional season number to filter by.' This goes beyond property names and types.

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 tool lists scene exceptions (aliases) for a series, using the specific verb 'list' and resource 'scene exceptions (aliases)'. It distinguishes from create_alias by noting 'this tool reads them; use create_alias to add new ones.'

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 clear context for when to use this tool (to list aliases) and contrasts with create_alias for adding. However, it does not explicitly mention when not to use or other alternatives like delete_alias.

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