apple_maps_eta

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 discloses that driving is always returned while walking is only returned when requested, that cycling is unsupported, and what metrics are returned (live best, historic, free-flow, distance). It does not mention rate limits, auth, or side effects, but for a read-only estimation tool these are not critical. No contradiction with annotations exists.

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 three sentences long, with each sentence carrying distinct value: purpose, output details, and cost/alternative guidance. There is no redundancy, filler, or repeated schema information. The most important scoping detail (cheaper than directions) is front-loaded in the third sentence, but the purpose is stated first.

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 read-only ETA tool with no output schema, the description adequately explains the return contents (time estimates, durations, distance) and mode behavior, giving an agent enough to select and invoke the tool correctly. Minor gaps such as not defining 'free-flow' or output units do not hinder correct selection, and required parameters are fully documented in the schema.

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 baseline is 3. The description adds valuable context beyond the schema by explaining the `mode` parameter's behavior: driving is always reported, walking is available when requested, and cycling is not supported. This enriches the enum definition, though it does not add anything about coordinates or country beyond the schema's existing descriptions.

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 states the tool's function: 'Get Apple Maps travel-time estimates between two points.' It specifies the resource and the exact output (live best estimate, historic/free-flow durations, route distance) and differentiates it from the directions endpoint by noting it is cheaper and lacks cycling ETA. An agent can distinguish this from sibling apple_maps_directions without inspecting the schema.

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 provides when-to-use guidance ('Cheaper than the directions endpoint when only the time and distance are needed') and when-not-to-use guidance ('Apple has no cycling ETA; use the directions endpoint for cycling'). It names the alternative endpoint and the condition that selects it, leaving nothing to inference.

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