Skip to main content
Glama
Sign In

Cito API

by com.citoapi.api
OverviewDiscussionsAdmin

upcoming_schedule

Read-only

Upcoming matches/events for one game, with game-specific filters.

When to use:

  • "What's on this week?"

  • Calendar UI; team next matches

Prefer over: live_matches for not-yet-started fixtures.

Do not use when: only in-progress matches needed → live_matches.

Filter support (unsupported params are ignored with meta.warnings — do not assume filtering worked):

  • lol: hours, team (slug), league (slug)

  • cs2: team, from, to (ISO); hours not applied upstream

  • cod: team, tournamentId

  • dota2: limit/cursor primarily; team may be client-filtered where data allows

  • ufc: hours / from / to applied client-side after bout expansion (API has no hours); event shells labeled by event name; bouts use fighters[] corners

Parallel-safe: yes. Upstream cost: 1–2. Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }

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": {
      "game": "<game>"
    },
    "name": "upcoming_schedule"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoISO-8601 end bound.
fromNoISO-8601 start bound.
gameYesGame title: lol | cs2 | dota2 | cod | ufc | tennis | valorant. Example: "cs2".
teamNoTeam id or slug filter.
hoursNoHorizon in hours when from/to not set (default 72). Example: 48.
limitNoMax items to return (default 20, max 50). Example: 20.
cursorNoOpaque cursor from pagination.nextCursor only.
leagueNoLeague id or slug filter.
tournamentIdNoTournament id filter.

Output Schema

NameRequiredDescriptionDefault
okYestrue if the tool succeeded
dataNoResult payload when ok is true; null on error
metaYes
errorNo
partialNo
paginationNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • removedInput schema / properties / bestOf
      Removed value: -{
-  "description": "CS2 only: series length, 1, 3 or 5, or a comma list (\"3,5\"). \"3\" returns BO3 matches only (filtered by the API, so paging stays right).",
-  "examples": [
-    "3"
-  ],
-  "type": "string"
-}
    • changedInput schema / properties / game / description
      Previous value: -"Game title: lol | cs2 | dota2 | cod | ufc | tennis. Example: \"cs2\"."New value: +"Game title: lol | cs2 | dota2 | cod | ufc | tennis | valorant. Example: \"cs2\"."
    • changedInput schema / properties / game / enum
      Previous value: -[
-  "lol",
-  "cs2",
-  "dota2",
-  "cod",
-  "ufc",
-  "tennis"
-]New value: +[
+  "lol",
+  "cs2",
+  "dota2",
+  "cod",
+  "ufc",
+  "tennis",
+  "valorant"
+]
  2. Changed1 schema field changed
    • addedInput schema / properties / bestOf
      Added value: +{
+  "description": "CS2 only: series length, 1, 3 or 5, or a comma list (\"3,5\"). \"3\" returns BO3 matches only (filtered by the API, so paging stays right).",
+  "examples": [
+    "3"
+  ],
+  "type": "string"
+}
  3. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already cover safety (readOnlyHint, destructiveHint=false) and open-world access, but the description adds non-obvious behavior the annotations cannot express: unsupported params are silently ignored and surfaced only via meta.warnings, some filtering happens client-side (ufc, dota2), and upstream cost is 1–2 calls. This directly prevents an agent from trusting a filter that was never applied.

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?

Front-loaded one-line purpose followed by labeled blocks (when to use, prefer over, do not use, filter support, parallel-safe, example). The density is high but every line carries decision-relevant information and the unsupported-param warning is placed before the per-game list, where it matters most.

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 not be explained, and pagination is covered via the cursor param pointing at pagination.nextCursor. The gap is the enum's tennis and valorant values, which have no entry in the filter-support matrix, leaving their supported filters undefined; the relationship to the tennis_schedule sibling is also unstated.

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

Parameters5/5

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

Schema coverage is 100%, so a baseline of 3 would apply, but the description goes further with a per-game filter support matrix that the schema cannot encode — e.g. hours not applied upstream for cs2, ufc hours/from/to applied client-side after bout expansion, cod supporting tournamentId. That is exactly the meaning an agent needs to pick params correctly.

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 first sentence names a specific verb+resource ("Upcoming matches/events") and its scope ("for one game"), and the usage block immediately separates it from live_matches. An agent can distinguish it from siblings like live_matches or tennis_schedule 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.

Usage Guidelines5/5

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

It gives explicit use cases ("What's on this week?", calendar UI, team next matches), an explicit preference rule ("Prefer over: live_matches for not-yet-started fixtures"), and an explicit exclusion ("Do not use when: only in-progress matches needed → live_matches"). Both the positive and negative routing conditions are stated.

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

All Cito API 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