Skip to main content
Glama
Sign In

Refs

by video.refs
OverviewDiscussionsAdmin

Get a competitor UGC scan and its board

get_ugc_scan
Read-onlyIdempotent

One of your competitor UGC scans (from ugc_scan): its status and progress while the worker runs (queued → finding competitors → fetching ads → measuring → writing → summary → done), then the board: each competitor's winning UGC ads ranked by signal (days running, variants, reach, CTR percentile, views) with the one-line reason each won, and "what wins in your category" (top hooks, formats, lengths and offers) as markdown and structured fields. Ads already in the Refs library carry REF ids for get_blueprint, get_frames and plan_video; the scan's own ads carry ugc:: refs, and get_ugc_scan(id, film) returns one's blueprint. plan.prompt is a ready brief for planning the user's own UGC ad. Private to you; Pro, free in credits.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

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

Input Schema

NameRequiredDescriptionDefault
idYesA scan id from ugc_scan, a refs.video/ugc/… link, a ugc:<scan>:<film> ref, or the product link you scanned
filmNoA film from the board (its film id or ugc:… ref): returns its blueprint

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • removedInput schema / properties / context
      Removed value: -{
-  "description": "Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as \"a user\", \"the customer\", or \"an account\". Example: \"Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution.\"",
-  "type": "string"
-}
    • removedInput schema / properties / llm_model
      Removed value: -{
-  "description": "The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. \"claude-opus-4-8\", \"gpt-5.2\"). Used for analytics only. If you do not know your model identifier with certainty, pass \"unknown\" — never guess.",
-  "type": "string"
-}
    • changedInput schema / required
      Previous value: -[
-  "id",
-  "context",
-  "llm_model"
-]New value: +[
+  "id"
+]
  2. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare read-only/idempotent/closed-world, but the description adds genuinely new behavioral facts: an asynchronous worker with a named state progression (queued → finding competitors → fetching ads → measuring → writing → summary → done), that results are private to the caller, that it is a Pro feature, and that it consumes no credits. Those are exactly the operational and entitlement details annotations cannot express.

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?

Content is front-loaded with the core purpose and essentially every clause carries information (status stages, board contents, ref routing, plan.prompt, entitlement). The weakness is structure: it reads as one long comma-chained sentence, so the switch between board mode and blueprint mode is easy to miss on a single pass.

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

Completeness5/5

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

There is no output schema, so the description has to describe return values and it does so thoroughly: status/progress, the ranked board with its ranking signals and per-ad reasons, category-level winners in both markdown and structured form, ref namespaces, and the ready-to-use plan.prompt. Nothing an agent needs to interpret the response or decide the next step is absent.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3. The description still adds meaning the schema does not spell out: that the two arguments are a mode switch, where id alone yields the board and id plus film yields that ad's blueprint, and that REF ids in the board map to other retrieval tools. The only gap is that the accepted id forms are largely restated from the schema.

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

Purpose5/5

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

The description names a specific verb and resource and distinguishes itself from the sibling ugc_scan by identifying itself as retrieval of 'one of your competitor UGC scans (from ugc_scan)'. It then enumerates exactly what comes back: worker status stages, the ranked competitor board with per-ad signals, category-level winning hooks/formats/lengths/offers, and the blueprint mode triggered by the film argument.

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?

Usage context is clear: poll this while the worker runs to watch progress, then read the board once done, and call with film to descend into a single ad's blueprint. It also routes downstream work to get_blueprint, get_frames and plan_video when refs are present. What is missing is an explicit exclusion, e.g. a statement that ugc_scan is what you call to start a scan in the first place.

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

All Refs toolsInspect
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