Podyx MCP

podyx_customer_availability

Read-onlyIdempotent

Browse customer room availability windows or concrete setup start times by date range and optional duration; returns paged read-only previews without reserving slots.

Instructions

Browse customer room windows or concrete setup starts GET /api/v2/rooms/availability. Omit duration_minutes for physical room windows without a guessed setup/duration. Supply a positive duration for starts, with distinct concrete setup variants when setup_id is absent. Select date or paired date_from/date_to; at most 31 inclusive studio-local days. page/per_page SQL-page rooms (windows) or setups (starts); intervals_page/intervals_per_page independently page each target/day's derived intervals, with truthful totals. Duration uses nominal local wall minutes; gap starts are unavailable and overlap starts choose the earlier occurrence. A nominal end in a DST gap remains a native wall-time candidate with ends_at=null, end_status=gap_time and unverified calendar status; no resolved-end guarantee exists for it. Physical window gap boundaries resolve to valid matching local/UTC endpoints; midnight ends are next-day exclusive. verified means no unresolved configured guard, including no configured integration/room mapping or disabled guard; it does not claim Google was polled. checked_at is advisory and no hold is created; writes must recheck availability. Current public_api/account/key/availability:read authority is required; disabling headless new entry preserves authorized reads. Read/preview only. Follow all pagination; a quote does not reserve a slot or lock a price.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

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

Input Schema

Name	Required	Description	Default
`query`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.0Nov 7, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description layers on genuinely non-obvious behavior: gap starts are unavailable, overlap starts pick the earlier occurrence, DST-gap nominal ends return ends_at=null with end_status=gap_time, midnight ends are next-day exclusive, and 'verified' explicitly does not mean Google was polled. It also discloses that checked_at is advisory, no hold is created, and that required authority is public_api/account/key/availability:read — all well beyond the structured hints.

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?

Purpose and the core parameter rules are front-loaded, which is good, but the body degenerates into a dense jargon-heavy run-on ('truthful totals', 'headless new entry preserves authorized reads', 'native wall-time candidate'). DST and verification caveats deserve inclusion, yet they could be bulleted or trimmed without losing meaning.

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 11-field, nested, no-output-schema, dual-mode availability query, the description covers the essential calling contract: mode selection, date-range limits, dual pagination, DST edge outcomes, verification semantics, and authority requirements. It partially hints at return fields (ends_at, end_status, verified, checked_at), though a sentence on the overall response shape would close the remaining gap.

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?

With 0% schema description coverage, the description carries the full burden and largely succeeds: date vs. date_from/date_to pairing with a 31-day cap, page/per_page as SQL-level paging over rooms or setups, intervals_page/intervals_per_page as an independent paging axis over derived intervals, duration_minutes as nominal local wall minutes, and setup_id's role. room_id and the nested 'query' wrapper get no explanation, leaving a small gap.

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?

Description opens with a specific verb and resource ('Browse customer room windows or concrete setup starts') plus the underlying endpoint GET /api/v2/rooms/availability, and it explicitly separates two distinct modes (room windows vs. setup starts). It stops short of naming which sibling to prefer — e.g., podyx_v1_get_booking_availability or podyx_get_tour_availability — so an agent still has to infer that this is the room-based availability tool.

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?

Strong conditional guidance for the main decision points: omit duration_minutes for physical windows, supply a positive duration for starts, add distinct concrete setup variants when setup_id is absent, and use either date or paired date_from/date_to within 31 inclusive studio-local days. It also states 'Follow all pagination' and 'writes must recheck availability.' No explicit alternative-sibling routing is given, which keeps it from a 5.

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

Deploy Server