search_stock_photos
Search stock photos
Description
Agent-facing description — the exact text a connected model receives for this tool.
Search commercial stock-photo libraries and get back a NUMBERED CONTACT SHEET image plus structured results (ids, buy links, attribution). Provide 1-4 SHORT, CONCRETE visual phrases (2-6 words each) describing photographic subjects — e.g. 'doctor patient consultation', 'stethoscope on wooden desk'. Decompose a design brief into distinct subjects rather than sending art-direction prose. Look at the sheet, pick by badge number, then call get_image for a full-size watermarked comp of the chosen asset. Results are ordered by the vendor's all-time popularity ranking unless you pass sort — use 'newest' for fresh/less-used imagery or 'relevance' for tighter keyword matches.
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
| queries | array of string | yes | 1-4 short concrete visual subjects, 2-6 words eachitems: 1–4 · each: 2–80 chars |
| orientation | enum | no | one of: 'horizontal', 'vertical' |
| color | string | no | Dominant color as hex without '#', e.g. 4F21EA |
| people | integer | no | Number of people in the photorange: 0–4 |
| sort | enum | no | Result ordering: 'popular' (vendor all-time popularity — safe but cliché-prone), 'newest', or 'relevance' (keyword match strength)one of: 'popular', 'newest', 'relevance' · default: 'popular' |
Output
Returned as structured content alongside the tool's text and image content.
| Parameter | Type | Required | Description |
|---|---|---|---|
| results | array of object | yes | |
| sort | enum | yes | Ordering the vendor applied to these resultsone of: 'popular', 'newest', 'relevance' |
| shown | integer | yes | Results on the contact sheetrange: -9007199254740991–9007199254740991 |
| totalAvailable | integer | yes | Largest vendor-reported match count across the queriesrange: -9007199254740991–9007199254740991 |
| warnings | array of string | no | Per-query failures (e.g. vendor rate limits) — results may be thinner than the brief deserves |
results[] items
| Parameter | Type | Required | Description |
|---|---|---|---|
| n | integer | yes | Badge number on the contact sheetrange: -9007199254740991–9007199254740991 |
| source | enum | yes | one of: 'shutterstock', 'adobe' |
| assetId | string | yes | |
| title | string | yes | |
| buyUrl | string | yes | Purchase/license page for this asset — surface this to the user |
| attribution | string | yes | Credit line that must accompany the image wherever it is placed |
| comp | object | yes | Largest watermarked comp available via get_image |
comp
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | yes | |
| width | number | yes | |
| height | number | yes |