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

Annotations already convey mutability and non-destructiveness; the description adds behavior beyond them by explaining that enrichments occupy sposition between photos and that position defaults to the album end. This helps an agent anticipate placement semantics without contradicting the 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?

Two short sentences, front-loaded with the core action and enrichment types, then a single high-value positional default. No flff or repetition of schema content.

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 write tool with no output schema, the description covers the conceptual purpose, the three type variants, and the one non-obvious behavioral default. It does not explain return values, but this is a minor gap for an insert operation with a fully self-describing 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 paramter baseline is 3. The description adds semantic value by explicitly stating the default placement behavior of after_media_item_id, which is useful for constructing a valid invocation.

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?

Names a specific operation, 'Insert an enrichment into an album,' and enumerates the three concrete enrichment kinds: text caption, named location, or map between places. The phrase 'enrichments sit between photos' implicitly separates this from sibling tools that add media to albums.

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?

Provides clear context about when this tool makes sense (adding storytelling elements between photos) even though it does not explicitly name sibling alternatives or exclusions. The positional default notes how the insertion behaves, which is actionable guidance.

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

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

Annotations indicate a mutating operation, and the description adds meaningnful behavioral constraints beyond them: app-created media and album, the picked-item limitation, the save_to_library prerequisite, and the 50-item cap. This gives an agent a clear model of what the tool will and won't accept.

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 sentences, tightly packed with the essential constraint and limit. No redundant or filler content; the key usage rule is front-loaded.

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 mutating tool with no output schema, this description covers the important preconditions, the main exception, and the batch limit. It doesn't describe response or error behavior, but those are less critical and not indicated in annotations.

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 coverage is 100% and parameter descriptions are alraedy informative. The description adds extra semantic value by clarifying that album_id and media_item_ids must refer to app-created entities, and that picked media must be uploaded first, which is not captured in the schema.

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?

States a specific verb and resource: adding media items to an album. Clearly distinguishes itself by emphasizing the app-created constraint on both sides, which differentiates it from operations like remove_from_album and create_album_with_media.

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?

Explicitly states when this tool applies: both the media items and the album must be app-created. It also gives an explicit exclusion and alternative: picked items cannot be added directly and must first be uploaded via save_to_library.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds diagnostic nuance: it inspects the actual grant scopes and warns that two failure modes look similar but are fixed differently, which is useful beyond the 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?

Two sentences, each with a distinct job: define the report and give the triggering scenario. No filler or repetition.

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?

The tool is a simple optional-parameter read-only diagnostic, and the description states its output dimensions and when to invoke it. With annotations covering safety, nothing needed for correct invocation is missing.

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 optional 'account' parameter is fully documented in the input schema. The description adds nothing about the parameter, so the baseline 3 applies.

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?

States a specific verb ('Report') and resource ('server can reach Google Photos'), plus the three outputs: reachability, acting account, and actually granted scopes. This distinguishes it from sibling list_accounts (identity only) and quota_status (usage), so an agent can select it without inspecting schemas.

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 an explicit trigger: 'Call this first when anything returns a permission error' and explains why with the missing-scope vs revoked-token distinction. It does not mention when not to use it or name alternatives, but the context is clear.

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

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

Annotations already declare this as safe, read-only, idempotent, and non-destructive. The description adds behavioral context beyond those hints: `ready` flips to true on confirmation, and prolonged false suggests the user hasn't opened the link. This explains the polling lifecycle without contradicting the 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?

Two short paragraphs, each earning its place: the first states purpose and the core `ready` behavior, the second gives operational polling guidance. No filler or redundant repetition 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 simple polling tool, the description covers what the agent needs: how to start the poll, what `ready` indicates, how often to poll, and when to abandon polling. The optional account parameter is fully described in the schema, and no output schema exists to complicate expectations. The guidance about asking the user handles the realistic failure case.

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 both `session_id` and `account`. The description reinforces that the session comes from start_pick_session and implies polling frequency is referenced from that call, but it adds little beyond the schema. 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 opens with a specific verb and resource: 'Poll a picker session started by start_pick_session.' It clearly defines the tool's responsibility and gives the key semantic detail that `ready` is true once the user confirms a selection. This distinguishes it from sibling tools like start_pick_session and list_picked_media.

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 provides explicit guidance on how to poll: respect `poll_interval_seconds`, avoid tight looping, and stop polling after a few minutes to ask the user. It names the originating tool and gives a clear 'when not to continue' condition, which is strong usage guidance for an agent.

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

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

There are no readOnly or destructive annotations, so the description carries the behavioral disclosure burden. It does disclose meaningful side effects: the album is private, belongs to this app, and is created empty, which explains why it is editable later. It doesn't mention permissions or reversibility, but for a simple create action this is solid context.

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 sentences, front-loaded with the core verb-object, followed by ownership/privacy context and next-step usage. Every sentence earns its place; there is no redundant wording or filler.

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 simple 2-parameter create tool with no output schema, the description covers what is created, the privacy and ownership model, and how to proceed afterward. It does not explicitly describe the return value or name the sibling create_album_with_media, but the reference to passing album_id when uploading implies the created album exposes an album_id, which is enough in context.

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?

Both parameters are fully documented in the schema, so the description does not need to repeat parameter details. The mention of album_id is useful workflow guidance but does not add semantic detail about this tool's own parameters beyond what the schema already provides.

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 verb and resource: it creates a new, empty album in the user's Google Photos. It also distinguishes itself from siblings by emphasizing 'empty', 'private', and 'belongs to this app', which separates it from create_album_with_media and the album management tools.

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?

It explains the intended workflow: create the empty album, then add items later via add_to_album or by passing album_id when uploading. It does not explicitly name create_album_with_media as the alternative when an album should be created with items, so it lacks an explicit when-not-to-use statement.

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

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

Annotations already mark destructiveHint=true, and the description adds important behavioral context beyond that: 'There is no API to delete uploaded media', 'Requires confirm: true', and 'leaves no empty album behind if the uploads fail'. This meaningfully discloses consequences and transactional behavior, exceeding what the annotations alone provide.

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 brief and front-loaded with the primary purpose in the first sentence, followed by high-value caveats and constraints. Every sentence adds operational information without redundancy.

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 composite mutation tool with six parameters and no output schema, the description together with the rich schema covers purpose, safety, limitations, and alternatives. It could mention what the tool returns, but that is not essential for correct selection and invocation given the schema's completeness.

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 every parameter fully. The description reinforces 'Up to 20 URLs' and 'Requires confirm: true', but adds little new parameter meaning 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 states a specific verb and resource: create an album and upload files in a single step. It explicitly names the three siblings it composes (create_album, upload_from_url, add_to_album), clearly distinguishing it from them.

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 says this tool saves three round trips over the listed alternatives and notes that it leaves no empty album behind if uploads fail, giving a clear reason to choose it over the multi-step flow. It also warns about the irreversible nature of uploads, which helps the agent decide when caution is needed.

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

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

Beyond the annotations, the description adds valuable behavioral context: it costs no API call and no quota, and incorrect category names are rejected rather than ignored. It also discloses that the tool reports what the Google Photos API cannot do, setting accurate expectations.

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 compact and front-loaded with the core purpose, then adds a short, high-value usage warning. Every sentence earns its place and no irrelevant details are included.

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 simple introspection tool with one optional parameter and strong annotations, the description fully covers what the tool returns, when to use it, and its cost/quota behavior. No output schema is needed because the return value is the list of accepted filters itself.

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 coverage is 100%, so the one optional parameter is already fully documented in the input schema. The description adds no parameter-specific meaning, which matches the baseline of 3 for high schema coverage.

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 names a specific verb (Return) and a precise resource (the filter values search_library accepts), and further narrows it to content categories, media types, and feature filters. It also distinguishes the tool from search_library by making clear it lists accepted values rather than performing searches.

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 clearly tells the agent when to call it: 'Read this before guessing a category name.' It also notes that a wrong guess is rejected, reinforcing the need to consult this tool first. It does not explicitly mention alternatives, but none are needed for an introspection tool.

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

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

Annotations already cover readOnly, idempotent, and non-destructive. The description adds meaningful behavioral details: it resolves the item's current base_url internally, works with a plain id, and never relies on a stale URL. It also discloses the return type (base64 + mime), going beyond what annotations express. No contradiction detected.

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?

Two concise, purposeful sentences. The first frontloads the action and output format; the second explains the URL-resolution behavior and its benefit. No filler or repetition of schema fields.

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 simple download tool with four documented parameters, no output schema, and a safety profile in annotations, the description covers the essential return information (base64 + mime), the scoping limitation (this app uploaded), and the id handling behavior. It does not detail error or size-limit behavior, but max_mb is already 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 value by specifying that media_item_id should be a plain id (not a pre-resolved URL) and that the tool handles resolution itself, which the schema's 'The media item to download.' does not convey.

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 ('Fetch') and resource ('bytes of a media item this app uploaded'), and clarifies that output is base64 with mime type. This clearly distinguishes it from siblings like get_media_item, which likely returns metadata rather than raw bytes.

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 the right context — using a plain media_item_id for an app-uploaded item when raw bytes are needed. However, it never explicitly contrasts with related siblings such as download_picked or get_media_item, so an agent gets no direct 'when-not-to-use' guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses important behaviors: the underlying URL is transient and auth-scoped, large files are refused, and the default size suffix is capped. These details help an agent anticipate failures and choose parameters correctly, going well beyond what annotations alone convey.

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 compact and front-loaded: the first sentence states the core function, the second gives the required input, and the following sentences provide only decision-relevant caveats. Every sentence earns its place, with no repetition of schema content or annotations.

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?

Although there is no output schema, the description specifies the return shape (base64 with mime type) and covers the critical operational constraints (auth, expiry, size caps, max_mb intent). The 4 parameters are fully documented in the schema, so nothing an agent needs to invoke correctly is missing.

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?

With 100% schema coverage, the baseline is 3, and the description adds extra meaning: it labels base_url as coming from list_picked_media and explains when to raise max_mb ('only when the caller genuinely needs the original'). The size and account parameters are well documented in the schema, and the description enriches the two most context-sensitive 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 states the action ('Fetch the bytes') and the resource ('an item the user picked'), and specifies the return format (base64 with mime type). It also ties the input to list_picked_media, which scopes the tool distinctly from library download tools. However, it does not explicitly name or contrast the sibling download_media_item, so sibling differentiation is achieved only implicitly through the 'picked' vocabulary.

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 gives explicit when-to-use guidance: 'Use this rather than giving a base_url to the user or to another tool,' with the concrete reasons (auth header, size suffix, expiry within the hour). It also advises on max_mb, telling the agent to raise it only when the caller genuinely needs the original. This is strong, actionable routing guidance.

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

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

The description adds substantial behavioral context beyond the readOnlyHint/openWorldHint/idempotentHint annotations: what fields are returned, the special meaning of a 404 (album exists but not app-created), and a hard time-based scope limitation (since 2025-04-01). 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?

Two short paragraphs, the first front-loading the core action and result fields, the second packing troubleshooting and scope limitations into three tight sentences. Every sentence carries useful information with zero redundancy.

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-item read tool with no output schema, this is fully complete: an agent knows what it will get, how errors behave, which scope applies, and what the id originates from. The only omission is the optional account parameter, which is already covered by 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 coverage is 100% and both parameters are fully described in the schema. The description reinforces that album_id is the lookup key but adds no new semantics about the account parameter or value formats, so the baseline of 3 applies.

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: 'Fetch a single album by id', naming the exact return scope (item count, cover photo, sharing state). It clearly differentiates from siblings like list_albums by emphasizing single-album retrieval.

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?

It implies the correct usage context (when you already have an album id) and provides critical exclusions: the album must have been created by this app, and Google Photos native albums are invisible. It does not explicitly name an alternative tool (e.g., list_albums), but the guidance is clear enough for an agent to select this over fetching a list.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds meaningful context beyond annotations: the returned fields and the important limitation that only app-uploaded media is accessible. This is useful behavioral disclosure, though it does not discuss error cases.

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 sentences deliver the core action, return contents, scope limitation, and the routing alternative with no wasted words. The most important information is front-loaded.

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 simple read-only single-item fetch with one required parameter and no output schema, this description is complete: it explains what is returned, the access boundary, and the correct alternative for other cases. The annotations cover idempotency and safety, so no critical call-time information is missing.

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 both parameters are already documented. The description reinforces that media_item_id is the lookup key and adds the return fields, but it does not add meaning to the account parameter beyond what the schema already provides. 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 uses a specific verb ('Fetch') and resource ('a single media item by id'), and states the key returned fields: dimensions, creation time, and description. It also explicitly distinguishes itself from start_pick_session, which is the sibling for reaching non-app-uploaded library content.

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 clearly states when to use this tool (fetch one media item by id) and when not to ('To reach anything else in the user's library, use start_pick_session'). The scope boundary—only media uploaded by this app—gives an agent a concrete decision rule.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable beyond-annotation context: the 50-item cap, the app-only media scope, and the partial-failure behavior where unreadable IDs appear in 'failed' instead of failing the whole call.

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 tight sentences, each earning its place: the core capability, the preferred-use and scope guidance, and the failure behavior. The most important information is front-loaded and there is no redundant filler.

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 batch retrieval tool with rich annotations, complete coverage of parameters in schema, and clear behavioral notes, the description leaves no material gap. It explains quota implications, scope, alternatives, and partial-failure semantics without needing an output 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 coverage is 100%, so the baseline is 3. The description adds meaning by clarifying that media_item_ids are batched, limited to 50, and that individual failures are handled gracefully via a 'failed' field. This enriches the parameter's practical semantics beyond the schema.

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 uses a specific verb ('Fetch'), states the resource ('media items by id'), and gives a clear bound ('up to 50 ... in one call'). It also distinguishes itself from the singular get_media_item and from start_pick_session, making the tool's unique role unmistakable.

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 says to prefer this over repeated get_media_item calls and explains why. It also provides the exclusion condition: for anything beyond app-uploaded media, use start_pick_session. This is direct, actionable routing guidance.

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

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

Annotations already mark the operation read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond those: the tool reveals the default account behavior, and it explicitly notes the call incurs no API cost. It doesn't describe output format, but no output schema exists and this is a simple list operation.

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 compact paragraphs with no wasted words. The main purpose is front-loaded in the first sentence, and the second sentence explains downstream usage and cost without redundancy.

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 no input parameters and ample annotations, the description covers everything an agent needs: what accounts are shown, how the default is represented, and how to use the returned names in other tools. The lack of an output schema is mitigated by the direct description of the listing content.

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?

The tool accepts zero parameters, so the schema fully covers parameter semantics (100% coverage). Baseline for zero parameters is 4; the description's mention of the `account` parameter on other tools clarifies how the returned names are consumed, adding slight context but not changing this tool's schema.

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 starts with a specific action and resource: 'Show every Google account this server can act as,' and uniquely distinguishes this tool from siblings by also revealing that it identifies the default account when no account is named. This separates it clearly from auth_status or quota_status.

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?

It states when to use the results by instructing the agent to 'Pass one of these names as `account` on any tool to act as that library instead of the default.' It also adds a cost characteristic ('Costs no API call') that informs decision-making, though it doesn't name alternative tools or exclusion criteria.

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

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

Beyond the readOnly/idempotent annotations, the description reveals important non-obvious behavior: only app-created albums are returned, user-created albums are hidden due to a scope boundary, results are ordered newest first, and pagination is required via next_page_token. These are operational details an agent needs before calling.

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 sentences deliver the core purpose, the critical scope limitation, and the pagination instruction with no filler. The most decision-relevant information is front-loaded.

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 paginated list with no required parameters, the description covers scope, ordering, a key availability boundary, and how to continue paging. The lack of an output schema is acceptable because the tool's list semantics and sibling context make its return expectations clear.

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?

The input schema already covers all three parameters at 100%, so the description does not need to repeat their formats. The description adds only a general pagination reminder without introducing new per-parameter meaning, matching the baseline for full schema coverage.

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 action and resource: 'List the albums this app created, newest first.' It also distinguishes itself from album-related siblings by explicitly limiting results to app-created albums and noting that user-created Google Photos albums are not visible.

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 gives clear scoping context: it should be used for app-created albums, and user-created albums are unavailable to any scope since 2025-04-01. It does not explicitly name sibling alternatives like list_shared_albums, so it stops short of full alternative routing.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that: only app-uploaded media is returned, results are newest-first, and album scoping is optional, with no contradictions.

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 sentences front-load the core purpose and scope, then provide the alternative and pagination. Every sentence carries distinct useful information with no repetition.

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?

The description is complete for a filtered read-only listing tool: scope, ordering, pagination, and routing to the appropriate sibling are all present. The rich annotations and fully described schema cover the remaining safety and parameter context.

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?

All four parameters are fully documented in the schema, so the description does not need to add parameter-level detail. It slightly reinforces album scoping and pagination but adds no semantics beyond the schema.

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?

Description names the resource (media items), action (List), ordering (newest first), and scope (this app's uploads, optionally one album). It also explicitly contrasts with start_pick_session, so an agent can distinguish it from the closest sibling.

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?

States when to use it (listing this app's uploads) and when not ('To reach anything else in the user's library, use start_pick_session'). The pagination note gives a concrete operational instruction for continuing results.

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

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

The annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context beyond those annotations: empty results until confirmation, the ~1-hour expiry of base_url, and the need to use download_picked for actual bytes. This is exactly the kind of behavioral disclosure that helps an agent act safely.

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 compact and front-loaded: the core purpose appears first, followed by the prerequisite call, then the crucial download guidance. Every sentence earns its place and no filler is present.

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 list tool with 100% schema coverage, the description covers the non-obvious return behavior (empty until confirmed), the expiring base_url, and how to access actual bytes. No output schema exists, but the key behavior an agent needs to call and interpret this tool correctly is present.

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?

All four parameters are already fully documented in the input schema, including session_id's origin from start_pick_session, pagination with next_page_token, and account selection. The description does not add parameter-level meaning beyond the schema, so the baseline of 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 and resource: 'Return the media items the user selected in a picker session.' This clearly distinguishes the tool from library search, album listing, and item download, and is consistent with the title.

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 tells the agent to call check_pick_session first and explains that the result is empty until selection is confirmed. It also routes actual byte retrieval to download_picked rather than exposing the expiring base_url directly, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond those annotations: the app-only scope, the inclusion of share links, and the API limitation that user-created Google Photos albums are invisible as of 2025-04-01.

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 with no fluff. The core function is front-loaded in the first sentence, and the critical scope limitation is stated concisely in the second. Every sentence 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 read-only, idempotent list tool with zero required parameters and a fully documented schema, the description covers everything an agent needs to invoke it correctly: what it returns, what scope it operates under, and an important API constraint. The lack of an output schema is not a serious gap because the description explicitly mentions share links and the pagination parameter is already documented.

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 parameters limit, account, and page_token are already fully documented in the schema. The description does not add parameter-specific guidance, which is acceptable because the baseline for full schema coverage is 3 and no extra semantic burden is placed on the description.

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 uses a specific verb ('List') and a specific resource ('shared albums this app created'), and clearly states the result includes share links. It also distinguishes itself from general album listing by explicitly excluding albums the user created directly in Google Photos, preventing confusion with sibling tools like list_albums.

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 gives clear context about when this tool applies: only albums created by this app are listed, and user-created Google Photos albums are not visible. It does not explicitly name an alternative tool, but the scope constraint effectively tells an agent when not to rely on this tool.

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

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

Adds a critical behavioral caveat beyond what annotations provide: the count is 'a floor rather than a true reading' because it is 'counted by this process since it started.' This prevents the agent from over-trusting the number as the authoritative Google Cloud quota figure. It also discloses the specific limits and reset period. No contradiction with readOnlyHint=true.

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 sentences with distinct jobs: what it reports and the limits, the measurement caveat, and when to call it. Every sentence earns its place; there is no filler or repetition of the title.

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 0-parameter status tool with rich annotations, the description covers what is measured, both quota types, limits, reset time, the floor caveat, and recommended usage timing. The lack of an exact return format is a minor gap since the reported quantities are already specified.

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?

The tool has 0 parameters and an empty schema (100% coverage trivially), so the baseline of 4 applies. There are no parameters in need of explanation or compensation.

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 uses a specific verb ('Report') and resource ('the Google Cloud project's daily budget') with concrete limits (10,000 API requests, 75,000 media-byte requests) and a reset time (midnight UTC). No sibling tool covers quota, so it is unambiguous which tool this is.

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 two explicit trigger conditions: check before a long batch, and check when calls start failing with RESOURCE_EXHAUSTED. It does not name alternatives or when-not-to-use, but none of the 28 siblings competes for this role, so the context is still clear.

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

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

The description discloses meaningful behavioral traits beyond the annotations: it uses the current access token, and unlike named tools, it does not shape responses, handle pagination, or explain errors. The annotations are neutral on safety, so this added context helps the agent anticipate raw output and error behavior.

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 compact and front-loaded: it defines the purpose in the first sentence, explains the mechanism in the second, and then gives usage guidance. Every sentence contributes value without redundancy.

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 an arbitrary endpoint escape hatch, the description covers the essential context: when to use it, the auth mechanism, and the trade-offs versus named tools. The parameter details are fully handled by the schema, so nothing critical is missing for invoking the tool 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?

The input schema already describes all six parameters with full coverage, including enums, defaults, and examples. The description adds little parameter-level detail, but with 100% schema coverage, no additional compensation is needed.

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 defines the tool as an escape hatch for unwrapped Google Photos endpoints, stating exactly what it does: send a path relative to the API root with the current access token. It also distinguishes itself from the sibling named tools by positioning raw as the fallback for API capabilities not yet covered.

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 says to prefer a named tool where one exists and to reach for raw only when the API has something the tools do not cover yet. This gives the agent a clear decision rule for choosing raw over any sibling tool.

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

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

Annotations already indicate this is a mutating but non-destructive operation. The description adds the key behavioral detail that only album membership is affected, not the underlying media items. It also notes the per-call limit of 50, giving agents a concrete boundary beyond the schema's maxItems.

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 short sentences, front-loaded with the primary action and then adding the crucial non-destructive guarantee and the batch limit. Every sentence earns its place with no fluff or restated title content.

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 simple, non-destructive mutation with well-documented parameters and helpful annotations, the description is nearly complete. It does not explain return values or error behavior, but no output schema exists and the operation is straightforward. This is adequate for an agent to select and invoke the tool 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 coverage is 100%, so the schema already documents all three parameters including account behavior, album_id, and media_item_ids. The description adds little beyond the schema, but the 'up to 50 per call' phrasing slightly reinforces the batch limit. Baseline 3 is appropriate because the schema carries the semantic weight.

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 uses a specific verb and resource: 'Take media items out of an album.' It immediately clarifies the non-destructive scope — items stay in the library — which distinguishes this from deletion-style tools like delete operations. The sibling and title context reinforce that this is the album-membership removal tool.

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 gives clear operational context: use this to remove media from an album while preserving them in the user's library. It implies when not to use it, but it does not explicitly name alternatives like add_to_album or state exclusion conditions.

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

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

Beyond the annotations' destructiveHint, the description discloses that this creates a second copy, that the item becomes an app-owned normal media item, and that picked items are only readable for the session lifetime. This meaningfully clarifies the side effects and persistence model, which annotations alone do not convey.

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, purposeful sentences: main action, lifecycle context, and input requirement. Nothing is redundant; the critical constraints and side effects are front-loaded.

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 schema covers all parameters and annotations cover safety/destructive traits, the description gives everything needed to call it correctly: where to get base_urls, the limit, the confirmation requirement, and the persistence consequences. No output schema is expected, so return-value omission is acceptable.

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?

The input schema already has 100% coverage, fully documenting base_urls, account, confirm, and album_id. The description essentially restates base_urls' source and limit, which the schema already provides, adding no new parameter-level meaning.

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?

States a specific action: take picked items, upload them as app-created media, and make them usable by the app's read/describe/organise tools. It clearly distinguishes this from sibling tools like list_picked_media, download_picked, or upload_from_url by framing it as the bridge between the picker session and the app library.

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?

Provides clear workflow context: use after list_picked_media, because picked items are only readable during the session, and before the app's media tools can work on them. It names the exact input source and the confirm: true requirement, though it does not explicitly discuss when not to use alternatives.

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

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.

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

The description adds material behavioral context beyond the annotations: the link cannot be recalled once sent, unshare_album cannot retract content already saved by others, and confirm:true is required. This aligns with and enriches destructiveHint=true and openWorldHint=true, giving the agent a realistic sense of consequence before invoking.

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 short sentences, with the core effect front-loaded and the risk-related caveats placed immediately after. Every sentence adds distinct value: what it does, why it is unique, and what irreversible consequence to expect.

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 no output schema, the description still names the return value (a link). It covers uniqueness, irreversibility, the related unshare tool, and the confirmation guard. Combined with full schema coverage and rich annotations, no critical operational detail is missing.

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 album_id, account, confirm, commentable, and collaborative. The description reinforces the confirm requirement, but does not add detail about parameters beyond what the schema provides. 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 opens with a specific verb and resource: 'Turn an album into a shared album and return a link anyone can open without signing in.' It clearly distinguishes this from siblings by noting it is 'the one thing here that reaches people outside the account,' which separates it from create_album, update_album, and other internal operations.

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?

It explicitly states the unique use case: sharing with people outside the account. It also provides a direct alternative comparison with unshare_album, explaining the limitation that revoking cannot recall content already saved. This gives an agent clear routing guidance without needing to inspect other tools.

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context beyond annotations: it returns a picker_uri, requires user interaction to complete, and involves a stateful pick session with timing constraints. The caveat about empty results is especially valuable for agents interpreting the tool's output.

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 front-loaded with the core purpose, then provides the required follow-up workflow, then the critical pitfall. Every sentence adds value: no filler, no repetition of the schema or title, and the most important instruction ('Give that URL to the user and stop') is prominent.

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 no output schema, it fully explains the return value (picker_uri), the interactive nature, the required polling pattern, and the meaning of an empty result. It is complete enough for an agent to invoke and continue the workflow 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%: the single optional account parameter is fully documented in the input schema, including its default behavior and how to list accounts. The tool description does not add parameter-level detail, but none is needed because the schema already carries that burden. 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?

Description uses a specific verb ('Open') and resource ('Google Photos picker') and clearly differentiates from sibling tools by noting it is 'the only way to reach media this app did not upload itself.' This distinguishes start_pick_session from search_library and other media-access tools.

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?

Provides explicit when-to-use guidance: use when the user needs media from their ENTIRE library, because the Library API cannot see anything else. Also gives a complete follow-on workflow: hand the picker_uri to the user, then call check_pick_session until ready, then list_picked_media. Directly warns against calling list_picked_media too early, which is actionable guidance.

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

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

The description discloses concrete behavioral consequences beyond the annotations: people who already opened the link lose access, while anything they saved or downloaded remains with them. This gives the agent a clear picture of external impact and is consistent with the readOnly, idempotent, and destructive hints.

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?

Two concise sentences with no filler: the first states the action, the second states the human-visible consequence. Every sentence 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 simple mutation with one required parameter, useful annotations, and no output schema, this description is complete. The agent understands what will happen, what will not be destroyed, and how the account and album are specified via 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?

The input schema documents both parameters at 100% coverage, including album_id and account with clear descriptions. The tool description does not add much parameter-level detail, so the 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 uses a specific action verb ('Revoke') and a specific resource ('an album's share link'), and it states the result ('make it private again'). This clearly distinguishes it from siblings like share_album and update_album.

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 makes the intended use case unmistakable: call this when an album should no longer be shared. It does not explicitly contrast it with share_album, but the semantics and sibling context make the boundary obvious.

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

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

Annotations already convey readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds a non-obvious behavioral detail: the cover must already be a media item in the album, otherwise an error is returned. This is genuinely useful runtime behavior beyond what the annotations state.

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 with no redundant content. It leads with the main purpose and follows with the critical constraint. Every sentence contributes useful information.

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 relatively simple update tool, the description covers the core operation and the main error condition. The schema covers account defaulting and per-field omission behavior. A minor gap is the behavior when both title and cover_media_item_id are omitted, which is not addressed, but this does not meaningfully block correct use.

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%, with clear parameter descriptions for title, accountant, album_id, and cover_media_item_id. The description adds only a small cross-parameter constraint: that the cover must already be in the album, and that the operation can target title, cover, or both. This is modest added value over the schema, so 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 and resource: 'Change an album's title, its cover photo, or both.' This clearly distinguishes it from sibling tools like create_album, list_albums, and add_to_album. The title reinforcement also helps disambiguate it from update_media_description.

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 provides clear context for when to use the tool: renaming an album or changing its cover. It does not explicitly name alternatives or give when-not-to-use conditions, but the operation is distinct enough that a capable agent can infer the appropriate scenario. The note about cover items already being in the album is a useful precondition.

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

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

Beyond the annotations, the description adds important behavioral context: the restriction to app-uploaded media and the clearing behavior on empty string. It does not contradict the annotations and provides useful detail about how the operation behaves.

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 sentences front-load the core action, then add the key constraint and the clearing behavior. Every sentence earns its place and there is no filler.

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 simple mutation with rich schema coverage, the description covers the operation's scope and special empty-string behavior. It does not describe error cases or return values, but the annotations already convey the safety profile and the schema covers parameter semantics.

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 three parameters. The description adds real-world context about the description field and the app-uploaded scope, but it does not need to repeat parameter details.

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 uses a specific verb and resource: 'Write the description shown under a photo or video in Google Photos.' It also distinguishes this tool from related media tools by stating it only works on media this app uploaded.

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 gives a clear scope condition: only media this app uploaded, which helps an agent decide when not to use it. It also clarifies that an empty string clears the description, but it does not explicitly name alternatives; no sibling tool performs the same function, so the exclusion is sufficient.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds the crucial fact that media cannot be deleted through any API once uploaded, and it reiterates the confirm:true requirement. This goes beyond the annotations to explain why the action is destructive and irreversible.

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?

Two short sentences deliver the core purpose and the most important behavioral warning. The critical constraint about irreversibility is front-loaded in the second sentence, and every word contributes useful information with no padding or repetition of schema details.

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?

The combination of the description, detailed parameter schema, and annotations covers what an agent needs to invoke this tool correctly: the local path requirement, the optional album, the confirmation flag, and the irreversible nature of the action. It does not explain return values, but for an upload tool with no output schema, the absence is not a serious gap.

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 each parameter already has a meaningful description, including the confirmation requirement and account selection. The description adds little beyond clarifying that uploads are photos/videos from a local path, so it appropriately stays at the baseline rather than adding significant value.

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 first sentence names a specific verb (Upload), a concrete resource (photo or video), and a distinguishing source (a path on the machine running this server). This clearly separates the tool from URL-based uploads and other library operations, so an agent can identify the right tool without opening schemas.

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 gives clear context: use this tool for local file uploads, optionally into an album. It does not explicitly name alternatives like upload_from_url, but the local-path framing and sibling list make the intended use obvious. It provides no explicit exclusions, which keeps this just below a 5.

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

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

Adds critical behavior beyond annotations: no API deletion exists, the operation cannot be undone via this tool, requires explicit confirm=true, and is limited to 20 URLs. No contradiction with destructiveHint=true.

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 concise, front-loaded paragraphs: purpose, irreversibility/confirmation, and limit. Every sentence adds operational value without redundancy.

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 6-param mutation tool, schema covers all param semantics and annotations flag destructiveness; description adds irreversibility and confirmation requirements. It doesn't describe return/result behavior or error cases, but no output schema exists and the core invocation context is sufficiently covered.

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 coverage is 100%, so the baseline is 3. The description confirms the 20-URL limit and optional album insertion, but adds little beyond the schema's parameter 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?

Clear verb+resource: downloads files from public URLs and adds them to Google Photos, optionally into an album. It distinctly conveys its domain vs siblings like upload_file or add_to_album.

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?

Description implies usage context: for public URL ingestion into Google Photos, with optional album placement. It doesn't explicitly name alternatives or exclusions, but the public-URL framing plus sibling names makes when-to-use fairly clear.

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