Production List

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

Annotations already declare readOnly/idempotent/openWorld=false, so the safety profile is covered. The description adds useful context about result ordering ('active first') and the important exclusion ('Contact details are never included'), but omits pagination or result-size behavior.

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?

Two dense sentences; the returned-field list and the disambiguating purpose clause are front-loaded with no filler. Every clause earns its place.

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 single-param read tool with no output schema, it covers identity, returned fields, ordering, input formats, and a notable exclusion. The only gap is no mention of pagination or limits on the attached productions list.

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% and the schema has no description, so the description must carry the load. It does so by specifying three accepted input forms for id_or_slug (slug, id, or productionlist.com/production-contact URL), which is essential invocation knowledge not in the schema.

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+resource ('One production company') and explicitly enumerates the returned fields (description, categories, website, url, productions). The clause 'This is the tool for what is [company] working on' sharply distinguishes it from search_companies.

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 phrase 'This is the tool for what is [company] working on' clearly signals when to use it, and the accepted identifier formats (slug, id, URL) guide input selection. It does not explicitly name search_companies as the alternative for discovery or state when not to use it.

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

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

Annotations already declare read-only, idempotent, non-destructive, so safety is covered. The description adds genuinely useful behavior: contact details are never included, and the contacts field instead explains how members reach the production — a return-content caveat an agent could not infer from structured fields.

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?

A single front-loaded sentence that identifies the resource, identifier forms, return contents, and the query intent without filler. It is dense and long, but every clause carries information; nothing is redundant.

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 no output schema, the description carries the return-shape burden and does so by enumerating fields and the contacts caveat. It omits failure behavior (e.g., unknown slug) and pagination/size limits, which are minor for a single-record lookup.

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 100% (baseline 3), but the description goes beyond it by naming the concrete URL shape 'productionlist.com/production/…', which the schema only calls 'the page URL'. This removes ambiguity about which URL form is accepted.

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?

Specific verb+resource ('One production') with the accepted identifier forms, plus a concrete enumeration of returned fields (synopsis, stage, dates, locations, companies, people with roles). It is clearly distinguishable from siblings like search_productions and get_company.

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?

Provides an explicit intent trigger: 'This is the tool for who is producing / casting / directing X.' The identifier-based framing implies it is the lookup tool versus search, but it never explicitly states when to prefer search_productions instead, so no full 5.

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

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

Annotations already declare this is a read-only, idempotent, closed-world, non-destructive lookup, so the safety profile is fully covered. The description adds the useful framing that it is a recovery/reference tool, but says nothing about what the returned slugs look like or how they are cached/ordered. Adding some value over annotations, but modest.

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?

Two lean sentences: the first names what is returned, the second names the trigger condition. Both earn their place and are front-loaded with the payload description.

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 no output schema and no parameters, the description must carry the return contract, and it does so at a high level ('valid slugs for ... filters'). A slightly more explicit note on scope (all valid values, or the currently applicable set) would close the remaining gap.

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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies a no-argument lookup that returns the full taxonomy set; nothing more is needed on the parameter side.

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 the resource is a set of valid slugs for stage, type, status, and company category filters, which is specific and distinguishable from the sibling search/get tools. It does not use an explicit verb like 'list' or 'fetch' (the title carries that), but the output is unambiguous.

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?

It gives a clear symptom-based trigger: 'Call this when a filter is rejected.' That is actionable context an agent can act on without opening a schema. It stops short of naming alternatives or when-not-to-call (e.g. proactively vs reactively).

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

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

Annotations already declare readOnly, idempotent, non-destructive, which the description doesn't need to repeat. The description adds the return fields, useful context. But it says nothing about pagination behavior despite page/limit params, which is the main behavioral gap.

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?

Three tight sentences, front-loaded with the search axes, then returns, then the follow-up routing. Every sentence earns its place.

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?

Returns and follow-up are covered; the main omission is pagination semantics for page/limit and default page size, which an agent needs for a list tool. Otherwise complete for a simple read search.

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 carry parameter meaning. It explains q (name substring) and category (slug from get_taxonomies), but page and limit are left entirely unexplained in both schema and description. Two of four params are undocumented.

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 (find) and resource (production companies) with the search axis (name substring via q, or category slug). Clearly distinguishes from search_productions by naming the entity searched.

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?

Explicitly says how to get valid category values (get_taxonomies) and names get_company as the follow-up for a company's productions, routing the agent across siblings. No ambiguity about when to use this versus the other tools.

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

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

Annotations cover safety (readOnly, idempotent) and open-world scoping, so the description doesn't need to re-explain those. The description adds useful behavioral detail: results sorted newest first, q matches title only (not companies/people), and phrasing guidance for citing url/updated_at. It doesn't mention pagination behavior or rate limits, but annotations already handle the core safety profile.

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?

Very dense and front-loaded. Each clause packs meaning, though sentence structure is a bit choppy with many semicolons and could be slightly more organized. No filler whatsoever.

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 11-param search tool with no output schema, the description covers the most critical filter semantics, sorting, and citation behavior. It's missing guidance on pagination limits and the type/status parameters, but overall it provides the necessary context for correct invocation.

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 64%, so the description carries some of the load. It clarifies q is title-only, enumerates stage values, explains city/state/country semantics with examples, and defines since/updated_since precisely. However, it doesn't cover page, limit, type, or status parameters, leaving gaps for a tool with 11 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?

States a specific verb and resource: 'Search or filter film and TV productions.' Clearly distinguishes from get_production (single lookup) and search_companies (different resource), though it doesn't explicitly say it only returns productions matching filters vs. a full list.

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 explicit routing for common queries: stage=in-production for 'what is filming now,' stage=in-pre-production for 'what is coming.' Names the fields to cite. Doesn't explicitly say when to use this tool vs. sibling tools, but for a search endpoint the use case is self-evident.

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