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

Annotations already cover readOnly/idempotent/non-destructive, so 'Changes nothing' is redundant, but the description adds real non-obvious behavior: the four possible status values, newest-first ordering, and the crucial note that imageId stands in for a deploy file's content (fromUpload) so the photo is never sent. It omits pagination/size limits, which keeps it at 4.

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?

Roughly 85 words, front-loaded with the core purpose, and every sentence carries substantive information. The opening sentence is a long semicolon-chained run-on covering return shape, ordering, and statuses, which slightly hurts scannability.

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?

There is no output schema, and the description does the work of describing the returned structure (spots with photos, four statuses, links with recipient and Done state), which is exactly what is needed. Missing only edge details like result limits and whether the two result sets are separate top-level fields.

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 50%: linkId is documented in-schema and the description reinforces it by saying it restricts output to one link. siteId, the required parameter, is undocumented in both schema and description beyond the vague phrase 'a site's photo links'. Baseline 3 is appropriate; the description does not fully compensate for the gap.

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: it shows what came in through a site's photo links, enumerated as spots with their photos, statuses, and link recipients. This is clearly distinct from siblings like get_submissions (forms), publish_upload (which acts on one photo), and create_upload_link (which makes a link).

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 concrete usage context: 'Pass linkId for one link only' scopes the optional filter, and 'Never put a discarded photo on the site' tells the agent how results should be acted on downstream. It stops short of explicitly naming the follow-up sibling (publish_upload) or stating when-not to call this versus get_submissions, so it falls under the 5 bar.

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