GuideDoc Documentary Database

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only that the collections are "public" and that results are "canonical page links," which is mild extra context; nothing is said about pagination behavior or ordering.

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 short sentence with no filler and the resource front-loaded. It is not bloated, though its brevity edges toward under-specification rather than efficient precision.

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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. However, for a 5-parameter, enum-bearing listing tool with zero schema descriptions, the description leaves too much (filtering, pagination, kind semantics) undocumented.

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?

All five parameters (kind, page, limit, query, language) have 0% schema description coverage, and the description mentions none of them. An agent cannot learn from it how kind=topic differs from kind=genre, what query filters, or how page/limit interact.

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 ("public genre/topic collections and canonical page links"), which reads as a browse/catalog action distinct from the search_* siblings. It does not explicitly name the search_* tools it competes with, so the differentiation is only implied.

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 statement of when to use this over search, search_documentaries, or recommend_documentaries. The browse-vs-search distinction is left entirely to inference from the tool name and the sibling list.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description's only behavioral claim ('revalidate publication') is ambiguous and adds no concrete context such as whether validation gates the response, what triggers failure, or auth requirements.

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?

It is a single short sentence with no wasted words, so it is concise. However, the sentence is front-loaded with an obscure 'revalidate' clause rather than the resource/action, weakening structure.

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?

Although an output schema exists (so return values needn't be described), the tool has a required id plus a nested filter object and explorer_id, and the description leaves all of that and the usage context unexplained. It is far too thin for a nested-parameter, multi-sibling catalogue tool.

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%, and the description provides no meaning for any of the four parameters (id, filters, language, explorer_id) or the many nested FilmFilters fields. With low coverage the description is expected to compensate, and it does nothing here.

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 gestures at 'public editorial film details' but never states a clear verb+resource operation; 'Revalidate publication before displaying' is an odd framing that doesn't map to a recognizable action like 'fetch one film's details by id'. It does not differentiate itself from siblings such as catalogue_search, catalogue_related, get_documentary, or open_catalogue.

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 statement of when to use this tool versus the many sibling catalogue/search tools, no prerequisites, and no exclusions. The phrase 'before displaying' hints at a pre-display step but gives no actionable condition for selecting this tool.

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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that results come with reasons, a useful return-content hint, but says nothing about pagination caps, ranking behavior, or fallbacks when no related titles exist.

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 short sentence is front-loaded and waste-free, but at this length it is under-specified rather than concise: the required input and the filter surface go entirely unexplained.

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?

An output schema exists, so return shapes need not be detailed, but the definition still omits the required similar_to_id parameter, the meaning of the filters bag, and any disambiguation from recommend_documentaries. For a 5-parameter tool with a required anchor ID, that leaves the agent materially under-informed.

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% (only the nested country field carries any text), yet the description mentions no parameters at all — it never explains similar_to_id, page/limit semantics, or the large FilmFilters bag (genre, scope, topic, year ranges, languages). With such low coverage the description should compensate and it does not.

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 a clear purpose: returning related-documentary recommendations derived from public subjects and credits, with reasons attached. It does not, however, distinguish itself from the sibling recommend_documentaries, leaving the agent to guess which to call.

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 when-to-use guidance, no mention of prerequisites (notably that similar_to_id is required), and no routing away from the overlapping recommend_documentaries sibling. The agent gets no basis for choosing this tool over alternatives.

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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The only added behavioral claim, that the interface is not remounted, is a UI-state preservation detail of questionable relevance to an agent and is too vague to act on.

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?

It is a single short sentence with no padding, so it is concise, but it is concise by virtue of saying almost nothing rather than by editing out fat. Length is appropriate for a blurb, not for a search tool with a nested filter schema.

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?

An output schema exists, so return values need not be explained, but a 6-parameter tool with a nested filter object, pagination, a language const, and a patterned explorer_id gets no coverage at all. The description leaves the agent unequipped to call this tool correctly.

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?

Six parameters with 0% schema description coverage, including a nested FilmFilters object with ten fields and pagination bounds, and the description documents none of them. The agent gets no help on query, page, limit, language, explorer_id, or any filter semantics.

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 restates the name generically ('Search from the explorer') and leans on an opaque UI concept ('remounting its interface') rather than stating what resource is searched. With siblings like search, search_documentaries, and catalogue_film, an agent cannot tell what corpus this hits or how it differs from those tools.

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 statement of when to use this tool versus search or the catalogue_* siblings, no mention of explorer_id being the likely trigger for this call, and no exclusions. 'From the explorer' hints at a context but gives the agent nothing actionable.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds some behavioral context by noting the instance is 'temporary' and 'anonymous' and that selections are revalidated through a 'public gate', implying a validation step. It says nothing about failure behavior, rate limits, or what the gate rejects, so the added value is 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?

At two short sentences it is appropriately sized and front-loads the primary action. But the second sentence is a fragment whose meaning is unclear, so brevity comes at the cost of comprehension rather than through efficient phrasing.

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?

An output schema exists, so return values need not be described. Still, for a sync tool with a revision cursor, an ephemeral anonymous instance model, and a gating/revalidation step, the description omits the sync semantics, cursor behavior, and error conditions an agent needs to invoke it correctly.

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% and the description never mentions explorer_id or after_revision. For a cursor-style sync the after_revision parameter is behaviorally critical, yet neither the schema nor the description explains it. The description therefore fails to compensate for the coverage gap as required when coverage is under 50%.

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 gestures at a specific action (reading a new selection intent and revalidating it through a 'public gate'), which is more than a restatement of the name. However, 'selection intent' and 'public gate' are internal jargon an agent cannot map to a concrete operation or outcome, and nothing distinguishes this from siblings like catalogue_search or open_catalogue. Purpose remains vague.

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 when-to-use, no when-not-to-use, and no mention of any alternative sibling tool. An agent has no way to know whether catalogue_sync should be called instead of catalogue_search or open_catalogue, or in what sequence. Only the barest implied context (an existing explorer instance) is present.

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 establish readOnlyHint=true and destructiveHint=false, but the description adds real behavioral value: 'Never returns playback or private data' and the note that the URL is revalidated against a current public database gate. These disclose data-scope and freshness behavior 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?

Three short sentences, front-loaded with the core action and the safety guarantee. The 'same current public database gate as WebMCP' clause is somewhat jargon-heavy for the value it adds, but overall it is tight.

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?

An output schema exists, so return values need not be explained, and the description adequately covers the read and its data-scope limits. However, with 0% schema coverage on the single parameter and the URL-vs-id ambiguity, an agent is left with a gap in how to construct the call.

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% and the sole parameter is named 'id', yet the description frames the input as a 'public film URL returned by search.' This adds some meaning about what the id should contain, but leaves ambiguity over whether it is a full URL or an identifier, and gives no format details.

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 a specific verb and resource ('Read a public film URL returned by search') and names a sibling tool (get_documentary) for a distinct use case. It is disambiguated from get_documentary, though the 'URL' framing conflicts slightly with the 'id' parameter name.

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 ties usage to search output ('a public film URL returned by search') and routes to get_documentary for 'full public editorial details.' That is clear context, but it doesn't explicitly state when NOT to use fetch versus other sibling readers like get_article or get_person.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that only 'public' article text is returned, implying no privileged access, but says nothing about error behavior or missing/private articles. Adequate but not rich given the annotation coverage.

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 with zero filler; the action and the required input source are communicated immediately.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. For a two-param read tool the description is nearly sufficient, with the main residual gap being the undocumented language parameter.

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% and there are 2 parameters. The description only characterizes the 'id' as numeric (already implied by the integer schema type) and never mentions the 'language' parameter or its enum-locked 'en' value, leaving that parameter undocumented everywhere.

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 (Read) and resource (public article text), and grounds it against a sibling by naming search_articles as the source of the IDs it consumes. An agent can distinguish it from search_articles and unrelated siblings like get_person/get_documentary without opening the schema.

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 'using a numeric ID returned by search_articles' establishes the required workflow precondition (search first, then fetch). It gives clear context but states no explicit when-not or alternative fetch paths, so it stops short of full routing guidance.

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 readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value beyond that: full films open externally on GuideDoc 'with normal access requirements,' original titles must be preserved, and passing explorer_id mutates the explorer view.

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?

Front-loads the core action, then layers usage and behavioral notes. Mostly efficient, though 'Preserve original titles' and the access-requirements sentence are slightly tangential to invoking the tool correctly.

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?

An output schema exists so return values needn't be described; the description covers purpose, ID sourcing, filter propagation and the explorer-view side effect, leaving nothing an agent needs to call it correctly.

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 carry the load. It explains three of four params meaningfully (id source, filters retention purpose, explorer_id updating the active view); only the trivial const 'language' is left unstated.

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: 'Read and display a verified public documentary film in the GuideDoc explorer.' It is clearly the single-film retrieval tool versus the search/list siblings, though it never names those alternatives (search_documentaries, catalogue_film) to sharpen the distinction.

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 concrete selection guidance: use the numeric ID from current results or selected-film context, and pass current filters so subsequent recommendations retain them. It stops short of stating exclusions or naming the sibling tools an agent should prefer for search scenarios.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds meaningful scope context ('published', 'only their public documentary records'), hinting at a privacy/filtering boundary. It does not mention pagination behavior despite page/limit parameters existing.

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 with no filler, and the resource is stated immediately. It is efficient, though almost too terse given the four undocumented parameters it could have addressed.

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?

An output schema exists, so return values need not be described, and annotations cover the read-only safety profile. The remaining gap is parameter behavior (paging, language constraint) and selection guidance versus search_people, which the description does not address.

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% across four parameters, so the schema provides bare types and bounds only. The description adds no information about what 'id' identifies, nor about page/limit/language semantics, leaving the burden unmet for a lookup tool with paging 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 clear verb+resource: reading a published person's biography and their public documentary records. It scopes the data to 'published' and 'public', which helps distinguish it from get_documentary and search_people. However, it never names an alternative to route between, so sibling differentiation is implied rather than explicit.

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 when-to-use framing and no mention of alternatives such as search_people (to find a person) or get_documentary (for a specific film). The agent must infer that this is a lookup-by-id tool from the required 'id' parameter alone.

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/openWorld/non-destructive, so the safety profile is covered. The description adds real scope boundaries beyond that: it never touches accounts, subscriptions, invoices, or tickets, and never mutates a subscription. That is useful disambiguation, though nothing is said about caching, rate limits, or freshness.

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 short sentences, front-loaded with the positive capability before the negative scope. The line breaks are slightly awkward but no sentence is wasted.

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 an output schema present, return values need not be described. The description covers capability, scope exclusions, and a price-check usage hint, which is sufficient for a trivial read-only tool with one constant parameter.

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 single parameter (language, const 'en', default 'en') is never mentioned in the description, and schema description coverage is 0%. Because the parameter is a fixed constant with no decision value, the omission is low-impact, so baseline 3 applies.

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: reading public FAQs and finding country-specific plans/help/legal links. This clearly separates it from the documentary/article siblings (search_articles, get_documentary, get_person), though it never names an alternative explicitly.

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?

'Consult the plans page for current prices' gives one implied usage context, and the negative scoping ('never reads accounts... never purchases') tells the agent when not to use it. However, no sibling or alternative is named, so routing must be inferred.

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=true, openWorld=true, destructive=false. The description adds real behavioral context beyond that: nonempty queries default to all records ranked by relevance, empty arguments open all records newest-first, full films retain normal access requirements, and it forbids inventing films on no-match. That is meaningful operational disclosure.

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?

It front-loads the purpose well, but then bundles agent-behavior directives into a dense run-on of clauses, some of which overlap (query defaults and empty-args defaults could be tightened). It is serviceable but not cleanly structured or maximally economical.

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 an output schema present, return values need no explanation, and annotations cover the safety profile. The description fills in query interpretation, filter preservation, and no-match handling, making it largely complete for correct invocation despite the unsupported filter parameters.

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 carries the full burden, yet it only clarifies query semantics (bare titles, translation behavior) and the sort default split (relevance vs newest). The 11 nested filter fields (genre, scope, topic, country, director, festival, languages, durations) are left entirely to their names, leaving a substantial gap.

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 ('Search and display documentary titles, filmmakers or topics inside GuideDoc'), so the job is unambiguous. It does not name any sibling (catalogue_search, search_documentaries, recommend_documentaries) to help an agent distinguish it, which keeps it below a 5.

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 concrete when-to-use guidance ('use for bare or ambiguous titles before answering from another meaning') and when-not ('Honor explicit translation/unrelated requests'). It also covers edge cases (no matches, empty args, preserving user filters), but never names the alternative tools an agent should switch to, so it stops short of a 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 readOnlyHint/openWorldHint/destructiveHint=false, so the safety bar is low. The description still adds real context: the default scope is GuideDoc-available films unless another scope is requested, no viewing history is used, and passing explorer_id updates the active explorer view. These are behavior beyond what the annotations convey.

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?

Front-loaded with purpose, then scoping and parameter-related notes in short sentences. Mostly earns its space, though fragments like 'No viewing history.' are terse to the point of ambiguity about what behavior is being asserted.

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?

An output schema exists, so return values need no explanation, and the description covers the trickier semantics (similar-to referencing, scope default, explorer view update). It is mostly complete for a read-only recommendation tool, with the residual gap being the many undocumented pagination and filter parameters.

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 carry the load. It meaningfully clarifies similar_to_id (via the position reference), explorer_id (pass from active context), and the duration/subtitle/subject filters to preserve, but leaves page, limit, query, language, sort, and the genre/topic/country/year fields unexplained — a large gap against 7 top-level params plus a 13-field nested filter object.

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 ('Find and display similar documentaries with reasons') and grounds it in the GuideDoc explorer context. Clear enough to separate from generic search tools, but it never contrasts itself with the plausible sibling catalogue_related or search_documentaries, so the boundary is left to inference.

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 concrete when-to-use guidance for an unusual case ('more like the second one', use the ID at visible position 2) and instructs preservation of explicit duration/subtitle/subject filters. It stops short of naming alternatives to use instead when the user wants keyword search or general browsing.

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 cover the safety profile (readOnly, openWorld, non-destructive), so the bar is lower. The description adds real behavioral context beyond them: results reflect GuideDoc's catalogue and may be subject to territorial restrictions, which affects how an agent interprets empty results. It does not discuss result limits or pagination, keeping it short of a 5.

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 short sentences, front-loaded with the primary purpose and routing advice. Every sentence earns its place with no repetition of structured fields.

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 an output schema present, return values need not be explained, and the description covers purpose, the alternative tool, and catalogue/territorial caveats. An agent has everything needed to call this correctly against its many siblings.

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 single query parameter has 0% schema description coverage, so the description must compensate. It does so by enumerating accepted query semantics (concise title, director, topic, keyword) and emphasizing 'concise', which is genuinely useful guidance the schema lacks.

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 ('Find public documentary films') plus the searchable facets (title, director, topic, keyword), making the scope immediately clear. It also implicitly differentiates itself from search_documentaries by reserving filters to that sibling.

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 routes the agent: 'For duration, subtitle, year and audio filters use search_documentaries.' This names the alternative and the exact condition that selects it, leaving nothing to inference.

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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds that scheduled posts and private previews are excluded, but says nothing about pagination, result limits, or auth expectations.

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 short sentences, front-loaded with the core action and immediately following with the scope constraint. No filler or redundant restatement of the name.

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?

An output schema exists, so return values need not be explained, but the description leaves four undocumented parameters and no differentiation from the many sibling search tools. For a filtered search tool with 0% schema coverage, this is too thin to reliably drive 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 description coverage is 0% across four parameters (page, limit, query, language), and the description explains none of them. It does not clarify what query matches, whether language is fixed to English, or how paging works, so it fails to compensate for the coverage gap.

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 clear verb+resource ('Find published documentary articles') and adds a scope qualifier that scheduled posts and private previews are excluded. However, it does not distinguish this from near-identical siblings such as search, search_documentaries, or get_article, leaving the 'articles vs documentaries' boundary ambiguous.

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 when-to-use or when-not-to-use guidance and no mention of alternatives, despite a crowded family of overlapping search_* tools. The exclusion note describes result scope, not when to select this tool over search or search_documentaries.

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/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful traits beyond that: stateful query retention across turns, that explorer_id updates the active explorer view, and that audio/subtitle filters are independent. Missing pagination/result-count behavior, so not a 5.

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?

Purpose is front-loaded in the first sentence, with usage, state, and explorer guidance following compactly. Dense but each sentence carries operational information; slightly crowded with imperative rules.

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?

An output schema exists, so return values need not be explained. The description covers the explorer-context workflow, query style, filter independence, and language constraint. Pagination behavior is the main gap, but it's minor for this tool's 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?

Schema description coverage is 0% for 6 parameters, so the description must carry the burden. It clarifies query intent, that filters should be explicit, English-only metadata, and the explorer_id role, but omits page/limit pagination semantics and does not enumerate which filters exist (sort, scope, year ranges, etc.).

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: 'Search and display documentary films in the GuideDoc explorer.' An agent can tell it targets documentaries specifically, distinguishing it from search_articles/search_people. However it never names or contrasts with near siblings like catalogue_search or recommend_documentaries.

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 concrete query-composition advice ('concise title, director or topic terms and explicit filters') and follow-up behavior ('keep the latest query and filters... changing only what the user requests'), plus a note that unrestricted searches cover all records. It stops short of explicit when-not-to-use or naming alternative 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 already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered externally. The description adds useful domain scoping ('published' profiles, 'public' documentaries, implying unpublished content is excluded) but says nothing about pagination behavior or result ordering.

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 with no filler; the scoping qualifier ('published', 'public') is placed where it matters. It is efficient, though the brevity is partly what leaves parameters and usage unaddressed.

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?

An output schema exists, so return values need no explanation, and annotations cover safety. For a four-parameter search tool with zero schema description coverage, however, the definition leaves query syntax and pagination semantics for the agent to guess.

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 carries the full burden, and it never mentions query, language, page, or limit. The four parameters (including a const-constrained language field and page/limit caps) are left entirely unexplained in prose.

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 (published filmmaker/contributor profiles), and scopes it to public documentaries. This separates it reasonably from search_documentaries and get_person, though it never names the closest sibling (get_person) or clarifies ID-lookup vs search explicitly.

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 when-to-use guidance, no mention of alternatives such as get_person for a known individual, and no prerequisites. The agent must infer that this is a keyword search over people and cannot tell when to prefer it over sibling tools.

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