subway_store

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 does an excellent job: it explains that boolean flags are omitted when not published (so an absent flag is not a false one), and it clarifies the subtle distinction between 'open' (published status) and 'currently within opening hours.' It also discloses the return format details (E.164 phone, IANA timezone, Google Place ID/CID). The only minor gap is that it doesn't explicitly state whether this is a read-only operation, but the verb 'Get' and the absence of any mutation language make that clear enough.

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 dense but well-organized: it front-loads the core purpose, then lists the return fields, then explains the boolean-flag semantics, then clarifies the 'open' field, then connects to sibling tools. Every sentence earns its place. It's longer than the typical description, but the complexity of the return payload and the subtle flag semantics justify the length. It could be slightly tightened, but it's not bloated.

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?

For a single-parameter detail tool with no output schema, the description is remarkably complete. It covers the input source (sitemap), the full return payload, the semantics of boolean flags, the distinction between 'open' and current hours, and the relationship to sibling tools. An agent has everything it needs to call this tool correctly and interpret the response. The absence of an output schema makes the detailed return-field enumeration especially valuable.

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 100%, so the schema already documents the single 'path' parameter. The description adds value by explaining where the path comes from ('a GET /subway/sitemap entry') and by noting that store_id (not path) is what the menu and available-times tools take. This helps the agent understand the relationship between the parameter and the broader API. The description could have been more explicit about the format of the path, but the schema plus the sitemap reference is sufficient.

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 opens with a specific verb and resource: 'Get one Subway store's detail.' It then enumerates the exact fields returned (address, coordinates, phone, hours, timezone, Google Place ID/CID, franchise number, price range, services, meal types, flags), which makes the tool's purpose unmistakable. It also distinguishes itself from sibling tools by noting that store_id is the value that GET /subway/menu and GET /subway/available-times take, and that paths come from GET /subway/sitemap.

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 explicitly states the input source: 'Paths come from a GET /subway/sitemap entry.' It also explains the relationship to sibling tools (subway_menu, subway_available_times) by clarifying that store_id is the value those tools take, which helps an agent understand when to use this tool versus others. The distinction between 'open' (published status) and 'currently within opening hours' also prevents misuse.

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