Skip to main content
Glama

GuideDoc Documentary Database

Recommend similar documentaries

recommend_documentaries
Read-only

Find and display similar documentaries with reasons in the GuideDoc explorer. For "more like the second one", use the ID at visible position 2 in explorer context. Preserve explicit duration, subtitle and subject filters. Defaults to films available on GuideDoc unless another scope is requested. No viewing history. Pass explorer_id from the active explorer context to update its view.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "recommend_documentaries"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNo
limitNo
queryNo
filtersNo
languageNoen
explorer_idNo
similar_to_idNo

Output Schema

NameRequiredDescriptionDefault
dataYes
sourceNoGuideDoc public documentary information; catalogue availability is not a playback entitlement

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / source / default
      Previous value: -"GuideDoc public information only; full films require an eligible subscription and territory"New value: +"GuideDoc public documentary information; catalogue availability is not a playback entitlement"
  2. Changed2 schema fields changed
    • addedInput schema / properties / explorer_id
      Added value: +{
      +  "anyOf": [
      +    {
      +      "pattern": "^[0-9a-f]{32}$",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Explorer Id"
      +}
    • changedInput schema / title
      Previous value: -"recommend_documentariesArguments"New value: +"visual_recommend_documentariesArguments"
  3. Changed2 schema fields changed
    • addedInput schema / properties / language / const
      Added value: +"en"
    • removedInput schema / properties / language / enum
      Removed value: -[
      -  "en",
      -  "ca",
      -  "es"
      -]
  4. Changed1 schema field changed
    • addedInput schema / additionalProperties
      Added value: +false
  5. Added

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), and the description adds genuinely new behavior: results come with reasons, recommendations are not driven by viewing history, availability defaults to GuideDoc, and passing explorer_id mutates the explorer view state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Five compact sentences, purpose first, then resolution rule, filter handling, scope default, and explorer_id handoff. No filler and no repetition of structured fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema means return values need not be described, but for a 7-parameter tool with zero schema coverage the definition leaves several parameters (query, page, limit, sort, year/genre) unexplained. It is complete on the recommendation-specific mechanics but not on the general filter surface.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is near zero, so the description must compensate; it partially does by explaining explorer_id's view-updating role, how similar_to_id is derived from visible position, and that duration/subtitle/subject filters are carried through. However, page, limit, query, language, sort, genre, topic and year bounds remain undocumented in both places.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'find and display similar documentaries with reasons in the GuideDoc explorer'. The mention of the explorer and the reasons payload distinguishes it from plain catalogue search siblings, though it never names search_documentaries or catalogue_related directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives actionable when-to-use rules: resolve 'more like the second one' to the ID at visible position 2, preserve explicit duration/subtitle/subject filters, and default to GuideDoc-available titles unless another scope is requested. It lacks an explicit negative case naming the sibling to use for non-similar searches.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources