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.

Input Schema

TableJSON Schema

Name	Required	Default
`page`	No
`limit`	No
`query`	No
`filters`	No
`language`	No	en
`explorer_id`	No
`similar_to_id`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`data`	Yes
`source`	No		GuideDoc public information only; full films require an eligible subscription and territory

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 30, 2026

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"

Changed2 schema fields changedSep 30, 2026
- addedInput schema / properties / language / const
```
Added value: +"en"
```
- removedInput schema / properties / language / enum
```
Removed value: -[
-  "en",
-  "ca",
-  "es"
-]
```
Changed1 schema field changedSep 30, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
AddedSep 30, 2026

TDQS

A3.9/5.0

Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines4/5

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.

All GuideDoc Documentary Database tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?