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

Annotations only declare readOnly=false, openWorld=true, idempotent=false, destructive=false. The description goes far beyond: LOGO is silently downgraded to PROFILE (with a measurement date), responses are checked against the slot Google actually wrote and failures refund the credit, billing is per-photo and rejected photos are not charged, partial failures are never reported as full success, and confirm=false → preview vs confirm=true → publish. This is unusually rich behavioral disclosure.

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?

Dense and front-loaded: the core single-vs-batch instruction comes first, then category, then failure/billing behavior, then the sibling redirect, then safety. Every sentence carries operational information. It is long and somewhat sprawling in the middle (category enumeration plus the LOGO story), which slightly dents scannability, but nothing is 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 6-param mutation tool with an output schema, the description covers the input contract, the fraud/credit and partial-result semantics, the sibling alternative for post attachments, and the safety gate. Return-value shape is left to the output schema, which is correct. Nothing an agent needs to call this 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?

Schema description coverage is 0%, so the description must carry the load and does: it defines image_url vs image_urls semantics, enumerates all eleven category values with their meanings and the per-call scope rule, explains allow_any_ratio=true as skipping the cover-ratio check, defines confirm as preview/publish, and defines location as a gbp_list_locations value or a business name/domain. The 'publicly reachable direct image link, because Google downloads it server-side' note is genuine semantics the schema cannot express.

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+destination ('Adds one or SEVERAL PHOTOS to the Google Business Profile listing (visible on Maps/Search)') and immediately distinguishes scope from siblings by naming gbp_create_post as the tool for posts WITH photos and gbp_update_photo_category is implicitly not this. An agent can pick it apart from gbp_upload_video and upload_image without opening a 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?

Explicit routing: single foto via image_url, batch via image_urls (up to 10), batch called out as 'the normal case after upload_image'. Tells the agent to upload different categories in separate calls and redirects to gbp_create_post(image_url=...) for post attachments. When/when-not/alternatives are all present.

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