apple_maps_guides_publisher

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

No annotations are provided, so the description carries the burden. It discloses the return shape in detail (name, subtitle, website, guide count, cities, guides with fields) and the filtering behavior of city_id. However, it doesn't disclose potential error cases (e.g., invalid publisher_id), pagination, or whether the guide list is complete or truncated. For a read-only lookup tool, this is adequate but not rich.

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 two sentences, front-loaded with the main purpose and return fields, then the optional filtering behavior. It's dense but not bloated. The list of return fields is long but necessary for an agent to know what to expect. Slight deduction for the long enumeration, but it earns its place.

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-resource lookup with 100% schema coverage and no output schema, the description covers the essential: what it returns, how to filter, and where to get the id. It doesn't explain return value structure beyond the field list, but since there's no output schema, a bit more detail on the shape (e.g., nested structure) could help. Still, the field list is quite complete for an agent to invoke correctly.

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 all four parameters. The description adds context for publisher_id (where to find it) and city_id (must be from the publisher's own cities list), which is genuinely helpful. But lang and country are not mentioned in the description, and the schema already covers them, so the description doesn't need to add more. Baseline 3 is appropriate.

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 states a specific verb ('Get') and resource ('one Apple Guides publisher'), and enumerates the exact fields returned (name, subtitle, website, guide count, cities, guides with their fields). It clearly distinguishes from siblings like apple_maps_guides_publishers (plural) and apple_maps_guide (single guide) by emphasizing 'one publisher by id' and its guides.

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 explains the core usage: pass a publisher_id, and optionally a city_id to filter guides. It also tells the agent where to find publisher ids (guides home, publishers list, guide's publisher.id, or maps.apple.com/guides URL). It doesn't explicitly state when NOT to use this tool versus siblings like apple_maps_guides_publishers, but the singular/plural distinction and the id-based lookup are clear enough context.

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