Skip to main content
Glama
Sign In

SuVerse

by io.github.sudzikcoin
OverviewDiscussionsAdmin

Book a slot in the business’s own calendar (Square Appointments)

book_slot

🔴 ACTS FOR THE USER: call it only after the user has explicitly agreed to this exact action (what, where, when, who) — never on your own judgement. For a service whose business’s card shows a book action with method connected and no book in its cannot (a door the platform refuses for this account is marked there, with the reason, at every sync). Take a start_at from check_availability (slots) and the platform books it for the named customer; the answer is the platform’s own status (created = on the calendar awaiting confirmation · confirmed · declined). A time the platform does not offer is an unavailable error and nothing is booked. Idempotent by idempotency_key like place_order. Get the user’s explicit yes first. Follow the server instructions «HOW TO USE THE SUVERSE CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.

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": {
      "business_id": "<business_id>",
      "offering_id": "<offering_id>",
      "start_at": "<start_at>",
      "customer": "<customer>"
    },
    "name": "book_slot"
  }
}

Input Schema

NameRequiredDescriptionDefault
noteNo
customerYes
start_atYesISO date-time with an offset, as check_availability gave it
variant_idNothe service variation when the card lists several
business_idYes
offering_idYesthe service, from the card
idempotency_keyNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Beyond the annotations, it discloses the returned statuses (created/confirmed/declined), the `unavailable` error path where nothing is booked, and the requirement for explicit user consent. The only friction is the claim 'idempotent by idempotency_key' against `idempotentHint: false`; that is reconcilable because the key is optional, but it is not spelled out, so it reads as mild tension rather than a clean disclosure.

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

Conciseness3/5

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

The consent gate is correctly front-loaded, but the explicit-yes instruction is stated twice (opening line and closing line), and the trailing recitation of the server's 'HOW TO USE THE SUVERSE CATALOG' instructions is generic boilerplate that does not help invoke this tool. The emoji and capitalized warning add visibility but also bulk.

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?

For an open-world mutation with a nested customer object and no output schema, the description supplies the gating conditions, the source of the time, the outcome statuses, and the failure semantics, which is close to what an agent needs. The residual gap is the under-documented optional parameters and the ambiguous idempotency statement.

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 coverage is 43%, so the description needs to carry meaning, and it does explain start_at's provenance, that a customer is required by name, and the role of idempotency_key. It says nothing about `note` or `variant_id`, and its treatment of the customer sub-fields adds nothing beyond the schema's own descriptions, leaving meaningful gaps.

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 states a specific verb and resource (books a slot on the business's own calendar) and names the exact inputs that produce it (a `start_at` from check_availability plus a named customer). It is clearly differentiated from siblings by referencing place_order for the idempotency analogy and check_availability as the source of the time, so an agent can pick it out of the catalog 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 when-to-use preconditions: the business card must show a `book` action with method `connected`, `book` must not appear in `cannot`, and the user must have given an explicit yes to this exact what/where/when/who. It also states the upstream step (take `start_at` from check_availability), which is the alternative that must run first.

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

All SuVerse 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