bms_get_venue_details

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly lists the data returned (address, coordinates, amenities) and explains the input format for venue_code (code or full URL). It implies a read-only operation but doesn't explicitly state that, though 'retrieves' strongly suggests it. The description adds meaningful context beyond the raw schema.

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

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

The description is appropriately sized and front-loaded with a clear title line, followed by a succinct paragraph and then the Args section. There is slight redundancy between the title and the first sentence ('Get Cinema Venue Location & Geo Coordinates' vs 'Retrieves detailed cinema hall/theater metadata'), but the overall structure is efficient and scannable. No unnecessary fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (presumably describing return fields), the description doesn't need to explain the return structure. It covers the tool's purpose and both parameters adequately. It doesn't mention the default city value, but that's available in the schema. For a relatively simple read tool, the description provides enough context for correct invocation, though it could note that city defaults to 'mumbai' if omitted.

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

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

Schema description coverage is 0%, so the description must fully explain parameters. It does: venue_code is described as a BookMyShow code or full URL with examples, and city is described as a slug with examples. This goes well beyond the schema's minimal title and default value, providing clear, actionable guidance for both parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's function: retrieving cinema venue metadata including address, coordinates, and amenities. The verb 'retrieves' is specific and the resource scope (venue details) distinguishes it from sibling tools focused on cities, movies, events, and showtimes. The tool name and description align perfectly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description implies usage—when you need detailed venue info, this is the tool—but it doesn't explicitly contrast with siblings or state conditions for when to choose this over others. No alternatives are mentioned, but the narrow scope makes the intent clear enough for an agent to infer.

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