Search media by date, category or type

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safefy profile is covered; the description then adds genuinely useful behavioral context: results are scoped to app-uploaded media only, the Google Photos API has no free-text search, categories are Google's classifier rather than user tags, and album_id+filters is rejected by Google. This materially prevents wasted calls and no contradiction with annotations.

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?

Three short paragraphs, zero fluff. Core function front-loaded, folowed by scope/alternative, then the API limitation, then the interaction constraint. Every sentence carries information an agent needs; there is no redundant restating of the title or schema.

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 tool with 11 params, 28 siblings, and a notably idiosyncratic API, the description covers the critical risks: scope limitation, the main alternative workflow, the no-free-text constraint, category semantics, and the album_id incompatibility. There is no output schema and the description does not describe the return shape, but pagination is implied by the page_token/next_page_token schema docs — a minor gap only.

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% and the schema entries are already detailed (formats, defaults, page_token mechanics), so the baseline is 3. The description earns a 4 by adding conceptual meaning beyond the schema: it explains that categories are classifier-based rather than user-set tags and that the API lacks free-text search, which shapes how an agent chosses parameter values.

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?

Opens with a specific verb-resource pair — 'Filter media by date range, content category, media type or favourites' — and immediately defines scope: 'Only media uploaded by this app is returned.' It explicitly names the sibling it is not ('use start_pick_session'), so an agent can distinguish this from the album-picking workflow without opening any 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?

Gives explicit when-to-use (filtering app-uploaded media), when-not-to-use (anything else in the user's library → start_pick_session), and routes to a supporting sibling (describe_filter_capabilities for exact values). Also preempts a likely mistake by stating album_id cannot combine with any filter. Nothig is left to inference.

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