NicheDB

match_items

Read-onlyIdempotent

Which title, channel or fixture is this name? Give a file name, a release name or a playlist entry ("Top.Gun.Maverick.2022.1080p.mkv", "US: ESPN2 HD"); it is cleaned (year, season and episode, quality tags, playlist decorations) and matched by similarity. A matchup ("NFL: Chiefs vs Bills", "Lakers @ Celtics", "Rangers at Celtic 19:45") is answered by the fixture whose two teams those are, kicking off between 36 hours ago and 7 days ahead unless date narrows it. Each result carries a score in 0..1. Use screen for films and TV, channels for television channels, sports for fixtures.

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": {
      "q": "<q>"
    },
    "name": "match_items"
  }
}

Input Schema

Name	Required	Description
`q`	Yes	The name as written, e.g. Top.Gun.Maverick.2022.1080p.mkv or US: ESPN2 HD
`lat`	No	Query center latitude; requires long
`bbox`	No	west,south,east,north; west > east crosses the antimeridian
`date`	No	A day (YYYY-MM-DD) to look for a fixture on, plus a day either side, e.g. 2026-11-02
`kind`	No	Item kind: title, channel or fixture (optional), e.g. title
`long`	No	Query center longitude; requires lat
`sort`	No	Result order. distance (needs lat and long) puts the nearest first, e.g. "distance"; anything else keeps newest first
`unit`	No	Default km
`year`	No	A four-digit year to prefer, when known, e.g. 2022
`limit`	No	Rows to return, integer 1-50, default 5, e.g. 3
`radius`	No	Default 10; maximum 1000 km
`collection`	No	Collection slug: screen, channels or sports (optional), e.g. screen

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedNov 1, 2026

changedInput schema / properties / collection / description

Previous value: -"Collection slug: screen, channels or sports"New value: +"Collection slug: screen, channels or sports (optional), e.g. screen"

changedInput schema / properties / date / description

Previous value: -"A day (YYYY-MM-DD) to look for a fixture on, plus a day either side"New value: +"A day (YYYY-MM-DD) to look for a fixture on, plus a day either side, e.g. 2026-11-02"

changedInput schema / properties / kind / description

Previous value: -"Item kind: title, channel, fixture"New value: +"Item kind: title, channel or fixture (optional), e.g. title"

changedInput schema / properties / limit / description

Previous value: -"Default 5, max 50"New value: +"Rows to return, integer 1-50, default 5, e.g. 3"

changedInput schema / properties / q / description

Previous value: -"The name as written"New value: +"The name as written, e.g. Top.Gun.Maverick.2022.1080p.mkv or US: ESPN2 HD"

addedInput schema / properties / sort / description

Added value: +"Result order. distance (needs lat and long) puts the nearest first, e.g. \"distance\"; anything else keeps newest first"

changedInput schema / properties / year / description

Previous value: -"A year to prefer, when known"New value: +"A four-digit year to prefer, when known, e.g. 2022"

Changed6 schema fields changedSep 13, 2026

addedInput schema / properties / bbox

Added value: +{
+  "description": "west,south,east,north; west > east crosses the antimeridian",
+  "type": "string"
+}

addedInput schema / properties / lat

Added value: +{
+  "description": "Query center latitude; requires long",
+  "maximum": 90,
+  "minimum": -90,
+  "type": "number"
+}

addedInput schema / properties / long

Added value: +{
+  "description": "Query center longitude; requires lat",
+  "maximum": 180,
+  "minimum": -180,
+  "type": "number"
+}

addedInput schema / properties / radius

Added value: +{
+  "description": "Default 10; maximum 1000 km",
+  "exclusiveMinimum": 0,
+  "type": "number"
+}

addedInput schema / properties / sort

Added value: +{
+  "enum": [
+    "id",
+    "published",
+    "updated",
+    "distance"
+  ],
+  "type": "string"
+}

addedInput schema / properties / unit

Added value: +{
+  "description": "Default km",
+  "enum": [
+    "km",
+    "mi"
+  ],
+  "type": "string"
+}

Changed1 schema field changedSep 10, 2026

addedInput schema / properties / date

Added value: +{
+  "description": "A day (YYYY-MM-DD) to look for a fixture on, plus a day either side",
+  "type": "string"
+}

AddedSep 10, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare the operation as read-only, idempotent and non-destructive. The description adds meaningful behavior beyond the annotations: name cleaning, similarity matching, fixture time windows from 36 hours ago to 7 days ahead, and a 0..1 result score. It does not explain ambiguity resolution or failure cases, so 4 rather than 5.

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?

The description is dense but appropriately sized for a tool with 12 parameters. It front-loads the core question, then adds input forms, cleaning behavior, matchup handling, scoring and collection guidance. Every sentence contributes information the agent needs.

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?

The definition covers the main behavior, input normalization, fixture time window, result score and collection selection. With no output schema, it could say more about returned fields beyond score. The schema already documents all parameters, so the description is largely complete for correct invocation.

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 description coverage is 100%, so the baseline is 3. The description adds useful semantics beyond the schema by mapping collection values to content types and explaining how date narrows the fixture time window. Most other parameters such as lat, bbox, radius, sort and limit are left to the schema.

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?

The description states a specific matching function: it cleans messy media names and matches them by similarity to a title, channel or fixture. It gives concrete input examples and explains matchup handling. It does not distinguish this tool from sibling tools such as search_items, so it falls short of 5.

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?

It clearly explains when to use the collection values: screen for films and TV, channels for television channels, sports for fixtures. It also describes input forms such as file names, release names, playlist entries, and matchups. It does not explicitly name alternative tools or state when not to use this one.

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

All NicheDB 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.