Cinve

Listar películas

list_movies

Read-onlyIdempotent

Search movies by name across Venezuelan cinema providers, with optional city, cinema, and date filters to find current listings and showtimes.

Instructions

Busca películas por nombre. Cinepic requiere cinema_id (123300 Candelaria o 123301 VVIP Lido) y filtra funciones del día; Cines Unidos requiere city y permite cinema_id/date. Cinex devuelve catálogo general sin fecha/sede: solo provider, query y paginación. Supercines devuelve su cartelera vigente (con preventa), general o de una sede con cinema_id, sin fecha. Gran Cine devuelve los títulos con funciones en la fecha, con cinema_id o city opcionales. Los IDs pertenecen al proveedor y, en Cinepic, a la sede.

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": {
      "provider": "<provider>"
    },
    "name": "list_movies"
  }
}

Input Schema

Name	Required	Description
`city`	No	Nombre de ciudad tal como lo devuelve list_cities del mismo proveedor (p. ej. Caracas); no distingue tildes ni mayúsculas en Cines Unidos.
`date`	No	YYYY-MM-DD; por defecto hoy en America/Caracas para películas y funciones de Cinepic/Cines Unidos y funciones de Cinex, Supercines y Gran Cine.
`limit`	No
`query`	No	Filtra por nombre, sin distinguir tildes/mayúsculas.
`offset`	No
`refresh`	No	true: consulta al proveedor sin usar caché local; solicita revalidación HTTP. No garantiza que el proveedor haya actualizado su contenido.
`movie_id`	No	ID de película devuelto por list_movies del mismo proveedor; opcional en Cinex cuando se consulta una sede completa.
`provider`	Yes	Proveedor de cine; obtén capacidades y limitaciones con list_providers.
`cinema_id`	No	ID de sede devuelto por list_cinemas del mismo proveedor. No mezcles IDs entre proveedores. Si la sede incluye code_status, usa cinema_id solo cuando sea verified; los IDs directory-* no permiten consultas.

Output Schema

Name	Required	Description	Default
`items`	Yes
`total`	Yes
`status`	Yes
`partial`	Yes
`sources`	Yes
`provider`	Yes
`timezone`	Yes
`warnings`	Yes
`queried_at`	Yes
`next_offset`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 11, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds important behavioral context beyond that: provider-specific data availability, default date behavior, catalog vs showtime semantics, and the rule that IDs are provider-scoped and venue-scoped for Cinepic. It does not cover auth or rate limits, but the added provider behavior is substantial.

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?

The description is front-loaded with the core action and then moves through providers in a compact sequence. Every sentence carries provider-specific information, but the dense paragraph format makes it slightly harder to scan than a bulleted or segmented structure would be.

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?

Given nine parameters, one required field, an output schema, and strong annotations, the description is largely complete. It explains provider-specific behavior and venue scoping. Minor gaps remain around pagination, refresh semantics, and movie_id usage, but those are partly covered by the schema and output schema.

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 high at 78%, so the baseline would be 3. The description meaningfully supplements the schema by explaining which providers require cinema_id, which use city or date, which ignore date, and how provider-scoped IDs work. This materially improves correct parameter selection beyond the field-level descriptions.

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 opens with a specific verb and resource: 'Busca películas por nombre'. It then clarifies how the tool behaves differently across providers, which helps distinguish it from sibling tools like get_showtimes. The only minor gap is that it frames the tool primarily as a name search even though it also lists catalogs by provider, venue, and date.

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 gives explicit per-provider usage rules: Cinepic requires cinema_id, Cines Unidos requires city and allows optional cinema_id/date, Cinex supports only provider/query/pagination, Supercines returns current billboard without date, and Gran Cine optionally takes cinema_id or city. This is strong contextual routing. It does not explicitly name alternatives such as get_showtimes or list_cinemas, so it stops short of full when-not-to-use guidance.

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

Deploy Server