@hanoak/unsplash-mcp-server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.2.1
Disambiguation5/5
Each tool targets a distinct resource: users, topics, collections, and stats. Even though three tools list photos, they are clearly differentiated by source (user, collection, topic).
Naming Consistency5/5
All tools follow the 'unsplash_<resource>_<action>' pattern consistently. Verbs like search, get, and implicit list (user_photos) are clear and predictable.
Tool Count5/5
7 tools is well-scoped for an Unsplash integration. It covers the main resources without being overwhelming.
Completeness2/5
Core functionality is missing: no photo search, no single photo details, no user profile details (only search), no collection listing for a user, and no topic listing. The set feels incomplete for typical image discovery workflows.
Average 4.1/5 across 7 of 7 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 85 commits in the last 12 weeks
- Last stable release on August 19, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description replicates the readOnlyHint by saying 'Read-only', but it also adds useful context about 'latest featured' and pagination. It does not go beyond that to describe return values, ordering, or potential API-side behavior such as rate limits or clamped pagination, but the read-only annotation lowers the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the core action. 'Read-only' is redundant with the annotation and adds no value, but otherwise every sentence contributes. It is concise without being sparse enough to lose meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only paginated list tool with fully described parameters and no required inputs, the description is sufficient for an agent to invoke it correctly. No output schema exists, but the 'List collections' wording naturally implies a list of collection objects. More detail about return shape or ordering would be helpful but is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both page and per_page fully described. The description only mentions pagination generically and adds no meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (List), a resource (Unsplash collections), and a scope (latest featured, paginated). It does not explicitly distinguish from siblings like unsplash_get_collection or unsplash_search_collections, but the wording is specific enough that an agent can infer the tool is for browsing featured collections rather than searching or retrieving a single collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as unsplash_search_collections, unsplash_user_collections, or unsplash_get_collection. It does not mention any exclusions or conditions for choosing this over related list/search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true, so the 'Read-only' phrase in the description is redundant. However, the description does clarify the paginated nature and the user-scoped resource, which adds modest behavioral context beyond the annotations. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally compact: two short phrases front-load the core action and scope with no fluff. The only slight redundancy is 'Read-only', which duplicates annotation data, but the overall structure is still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list with fully documented parameters, the description is minimally viable. However, there is no output schema and the description doesn't describe what a returned collection object looks like or direct the agent on how to compare with the broader sibling list tool, leaving moderate gaps for an agent deciding whether this tool is the right one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so username, page, and per_page are each fully documented with types, defaults, and constraints. The description adds no extra parameter-level meaning; it just says 'a user's collections', which largely reflects the username parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear specific action ('List') and resource ('a user's collections'), and adds 'paginated' to convey the operation's shape. It is distinguishable from other user-level tools like unsplash_user_photos, though it doesn't explicitly name an alternative or contrast with the more general list_collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to prefer this over unsplash_list_collections, unsplash_search_collections, or unsplash_user_photos. Saying 'a user's collections' implies user-scoped listing, but no explicit conditions, exclusions, or sibling routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description's 'Read-only' merely repeats that. It adds mild behavioral context by stating the listing is paginated, but it does not disclose behavioral subtleties such as default ordering, clamping behavior, or whether the filter parameter can narrow results. The description does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, front-loaded statements with no filler. 'Read-only' is redundant with annotations but does not weaken the conciseness. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a simple read-only list operation with zero required parameters and no output schema, the description provides enough context for an agent to call it correctly. It adequately conveys the resource, the paginated behavior, and the safety profile. It could be strengthened by stating that it lists all topics when no filters are applied, but the schema's optional params make this inferable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters, so the baseline is 3. The description adds little beyond mentioning pagination, which is already implied by the page and per_page parameters. It does not clarify how ids interacts with pagination or what default ordering applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('List'), resource ('Unsplash topics'), and adds a useful parenthetical ('curated themes') and pagination detail. It is distinct from sibling listing tools by naming 'topics' explicitly, though it does not explicitly distinguish from very similar list tools like unsplash_list_collections or unsplash_list_photos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, nor any exclusionary context such as 'for a single topic use get_topic'. The description only states what it does, not when to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. Description adds 'Read-only' which is consistent but does not provide additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is short and front-loaded, with no wasted words. However, it is slightly under-informative for a complete description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter tool, the description is adequate but does not mention the return format or typical response fields, which would help an agent understand the tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and already explains the parameter. The description echoes 'ID or slug' but adds no new semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get), resource (single Unsplash topic), and identifier method (ID or slug). It distinguishes from sibling tools like unsplash_topic_photos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this vs alternatives. While the name implies simple retrieval, no usage context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description restates 'Read-only' without adding new behavioral context. No additional traits such as error behavior, rate limits, or return-format nuances are disclosed, but for a simple ID-based read tool the annotation coverage keeps this at a safe baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, with the key operation front-loaded in one clear sentence. The standalone 'Read-only' sentence is technically redundant with the readOnlyHint annotation, so it does not fully earn its place, but there is no wasted wording or unnecessary background.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only lookup, the description is complete: it identifies the verb, the resource, the identifying input, and the safety posture. A return-value description is not necessary since the tool name and action make the result clear, and the annotations fill in the read-only semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single 'id' parameter is already described as the Unsplash collection ID in the schema. The description only repeats 'by its ID,' adding no further semantic guidance such as where the ID comes from or how it should be formatted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get a single Unsplash collection by its ID.' It clearly distinguishes this from listing, searching, or modifying collections, and the 'single' qualifier plus ID scoping separates it from sibling tools like unsplash_list_collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied but not explicit: the description says to get one collection by ID, which suggests this tool is for ID-based single-collection lookups. However, it does not explicitly say when not to use it, such as directing users to unsplash_list_collections for multiple collections or to unsplash_collection_photos for collection contents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's 'read-only' adds little. It does add context about the default 30-day window and aggregate counts, but it does not disclose response shape or clarifies clamping behavior. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The key operation, data granularity, and default window are all front-loaded in the first sentence, and 'read-only' is a useful one-word safety signal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two documented parameters and no output schema, the description is largely complete. It could say a bit more about expected return values, but the purpose and call context are clear enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter schema coverage is 100%, so id and quantity are already documented. The description's phrase 'last N days (default 30)' adds minimal value beyond the schema, and it does not resolve the schema's confusing maximum/clamp mismatch.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('get'), a specific resource ('download and view totals for a photo'), and a clear time window ('over the last N days'). This distinguishes it from siblings like user statistics or collection/topic tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly implies when to use the tool, but it does not explicitly exclude alternatives or name related tools such as unsplash_user_statistics or unsplash_total_stats. The guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true. The description's 'Read-only' merely restates the annotation and adds no new behavioral context such as rate limits, pagination, or result volatility. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the primary action and target. However, 'Read-only.' is entirely redundant with the annotation, making it a small amount of non-essential information in an otherwise tight description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only listing tool, the description is complete enough. The purpose is clear, the parameter is fully documented in the schema, and no output schema is needed for an agent to understand that the result will be a list of collections.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter, id, is already described as 'The Unsplash collection ID.' The description's phrase 'given collection' only indirectly maps to the parameter and does not provide additional semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List collections related to a given collection.' It clearly identifies the action and target object, and the phrase 'related to a given collection' distinguishes it from sibling tools like unsplash_list_collections or unsplash_get_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: use this when you already have a collection ID and want related collections. However, it does not explicitly mention alternatives or state when-not to use this tool, leaving some routing burden on the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description simply repeats 'Read-only' without adding anything beyond the schema. The description does not mention clamping of quantity to a max of 30, which the schema notes, nor any response behavior. Since annotations cover the safety profile, this is acceptable but adds no extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence followed by 'Read-only'. Every token contributes to communicating the core purpose, and there is no fluff or repetition beyond the harmless echo of the annotation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity, read-only operation with two well-documented parameters, the description is nearly complete. It does not mention the clamp behavior or implicit maximum of 30 days, but the schema covers that, so nothing critical is missing for a safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both properties thoroughly documented, including defaults, limits, and the '@' instruction. The description only adds 'default N days (default 30)' which mirrors the schema, so it does not meaningfully increase understanding beyond the structured data.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Get') and a specific resource ('a user's download and view totals'), and clarifies the time window with a default. It distinguishes itself from related tools like photo statistics or total stats by focusing on per-user totals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance or comparison against sibling tools such as unsplash_photo_statistics, unsplash_total_stats, or unsplash_month_stats. The context is implied by 'a user's' as opposed to 'photo' or 'total', but an agent is given no explicit instruction on when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, covering side effects and access boundary. The description adds the qualifier 'public profile' but does not disclose other behaviors like response shape, whether the user must exist, or error semantics. Given the annotations, the bar is lower; this is adequate but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one clear sentence plus a short 'Read-only.' that is redundant with the readOnlyHint annotation. The core sentence is front-loaded and contains no fluff, but the redundancy prevents a top score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only tool with readOnlyHint and openWorldHint annotations, the description sufficiently captures the tool's function and scope. It lacks an explicit payload description or output details, but with no output schema the implied 'public profile' return value is enough for the simplicity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the usernname parameter fully: type string, minLength 1, description stating 'The Unsplash username (without the @)'. The description's 'by username' adds no extra semantics beyond the schema. With 100% schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), resource ('an Unsplash user's public profile'), and scope ('by username'), making the tool's purpose unmistakable. 'Public profile' distinguishes it from sibling tools like unsplash_user_photos, unsplash_user_collections, or unsplash_user_statistics, which fetch other aspects of a user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool to retrieve a user's public profile when you know the username. It does not explicitly mention alternatives or when-not-to-use, but the resource-scoping ('public profile') and the username requirement imply when it is appropriate compared to searching or other user endpoints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds details on the response structure (imgix URLs, fixed sizes, ready-to-use attribution) and pagination, giving a clear picture of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the core purpose and adding key details without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the output content but does not mention the overall response format (e.g., array, pagination metadata). Given no output schema, more detail on the return structure would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all 5 parameters with 100% coverage. The description does not add extra meaning beyond stating the output structure, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists photos in a topic with URLs and attribution. It distinguishes from sibling tools like unsplash_get_topic (topic info) and unsplash_user_photos (user photos).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not provide explicit guidance on when to use it versus alternative tools, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It adds valuable behavioral information beyond the annotations: only the fields passed are modified, the operation requires an authenticated owner, and the tool is not read-only. These side effects are more specific than the provided readOnlyHint/destructiveHint annotations, and there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and action-first, placing the core purpose before the auth prerequisite and safety note. Each sentence carries meaningful weight without excessive paraphrasing. The only slight redundancy is the final 'Not read-only' because the annotations already communicate this.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides the main operational context: who owns the photo, what can be changed, partial-update semantics, and a concrete login command. The lack of an output response shape prevents a perfect score, and the owner-only constraint could be stated even more explicitly, but the tool is callable with the given guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all 6 parameters thoroughly, so per-parameter detail is already handled. The description contributes the partial-update semantics and a short field list, but it repeats field names rather than adding new meaning to individual parameters. With 100% coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies an update action on a specific resource type ('photo owned by the authenticated user') and enumerates the exact metadata areas involved. It distinguishes itself from the many read/list/search sibling tools, though it does not name the other update_* tools as near alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear prerequisite: the user must have OAuth sign-in and provides the concrete command to run first. It conveys that this is a write operation and should not be considered read-only. It stops short of explicitly contrasting with unsplash_update_collection or unsplash_update_my_profile, so it does not reach a five.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description reinforces 'Read-only' and adds details about the returned data (name, username, bio, etc.), which provides useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words; the key action and result are front-loaded and clearly stated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides sufficient detail about return contents. It could include error or pagination specifics, but is adequate for a simple read-only search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds no substantial meaning beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches Unsplash users by keyword and returns paginated compact user profiles, distinguishing it from siblings like unsplash_user_photos which focus on a specific user's content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching users but does not explicitly state when to use or not use this tool versus alternatives, nor does it provide exclusions or context about when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. Description adds 'Read-only' which is redundant but not contradictory. No further behavioral details (e.g., rate limiting, caching). Description carries minimal extra value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (two sentences), front-loaded with primary action, no filler. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, description lists main returned items but omits return format (JSON object with specific fields). With no output schema, description could be more explicit about what 'and more' includes. Adequate for simple stat but could be slightly improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters (empty schema, 100% coverage). Description adds no parameter info, but none needed. Baseline 4 applies as schema covers all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves Unsplash-wide totals (photos, downloads, views, photographers), with a specific verb 'Get' and resource 'Unsplash-wide totals'. Description distinguishes tool from sibling tools that focus on specific users, topics, or photos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for aggregate statistics, but does not explicitly state when to use versus alternatives. However, the sibling tools are clearly different (user-specific, topic-specific), so context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, destructiveHint=false, and the description adds behavior beyond annotations: 'Only the fields you pass are changed' clarifies partial-update semantics, and the OAuth prerequisite explains the invocation flow. The phrase 'Not read-only' restates the annotation rather than adding new information, but there is no contradiction, and the added context helps an agent act correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short, purposeful sentences with the core function front-loaded ('Update the authenticated user's own profile…'), followed by carefully chosen behavioral and prerequisite details. It is tight and scannable; only the final 'Not read-only' redirects content also present in annotations, and that redundancy is minor.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 optional parameters, full schema coverage, and valid annotations, the description together with the schema covers the essential needs: what is mutated, the partial-update contract, and the setup requirement. There is no output schema, so the rubric does not require return-value documentation here; the only real gap is lack of an explicit note on what the response contains (e.g., the updated profile object), which is modest for this scenario.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — every parameter has a per-property description ('New bio text.', 'New Instagram username.' etc.) — so the baseline is 3. The description's 'Only the fields you pass are changed' reinforces the all-parameters-optional nature, but it doesn't layer new semantic detail on any individual parameter beyond what the schema already gives.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb and resource ('Update the authenticated user's own Unsplash profile'). The scope is crystallized by 'own' and 'authenticated', which unambiguously separates it from the read sibling unsplash_get_my_profile and from the photo/collection update tools, so an agent doesn't need to open the schema to understand which object is being mutated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use context and an explicit prerequisite ('Requires OAuth sign-in — run npx @hanoak/unsplash-mcp-server login first'), which conventionally stands in for the supported 'when' guidance. It does not explicitly name alternatives or state when-not-to-use (e.g., a pointer to get_my_profile for reads), so it stops short of top-tier with no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the mutation nature is covered. The description adds value by specifying that the collection is 'owned by the authenticated user' and requiring OAuth sign-in, which are meaningful behavioral and environmental traits 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The core purpose, ownership constraint, and authentication requirement are front-loaded, and each piece of information earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with only three optional parameters and no nested objects, the description covers the key operational requirements (ownership and authentication). It does not mention return value, but that is common for create operations and the output is likely a collection object.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: title, private, and description each have clear inline descriptions. The tool description does not add extra parameter semantics or examples, which is acceptable since the schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create') and resource ('a new collection') and constrains ownership to the authenticated user. It clearly distinguishes this from sibling tools like update_collection, delete_collection, and various read-only collection tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides necessary context: the tool requires OAuth authentication, and it gives a concrete prerequisite command. It does not explicitly name alternatives or when-not-to-use, but for a create operation the purpose is unambiguous and the authentication caveat is important guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and readOnlyHint=false; the description adds meaningful context on top: the operation is irreversible ('This cannot be undone'), requires prior OAuth authentication, and repeats safety guarantee 'Not read-only.' These statements are consistent with the annotations, so no contradiction. Only failure-mode behavior (401/403/404) is left undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences and every sentence earns its place: irreversibility and scope up front, the authentication prerequisite, and an explicit disambiguation that this is not read-only. No filler, no restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the essential facts are covered: what is deleted, the ownership constraint, irreversibility, and the login prerequisite. The only missing detail is behavior on failures such as a nonexistent or non-owned collection ID, which is minor for such a simple destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single required `id` parameter is already documented as 'The Unsplash collection ID' in the schema. The description adds no parameter-specific detail, and at this coverage level the schema carries the burden, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description pairs a specific verb ('delete') with a specific resource ('collection owned by the authenticated user') and stresses permanence. This differentiates it from siblings like create_collection and update_collection without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context is given: the target must be a collection owned by the currently signed-in user, and the exact OAuth prerequisite appears right in the description (`npx @hanoak/unsplash-mcp-server login`). It does not explicitly name exclusion conditions or reasons to prefer another sibling, but for a one-target destructive operation the usage signals are sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial detail beyond readOnlyHint=true: it explains pagination, availability of raw imgix URL with customization example, and fixed image sizes. This fully informs the agent about the tool's behavior and output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. First sentence captures purpose; second sentence delivers key behavioral detail. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers the return type (image URLs with sizes) and provides a customization hint. However, it could briefly mention pagination handling. Still, overall complete for the tool's scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions. The description only adds value for the output format, not for parameter usage. Baseline of 3 is appropriate since schema already explains parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'user's photos' with pagination and attribution, distinguishing it from sibling tools focused on search, topics, or stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for retrieving a user's photo collection, but does not explicitly compare to alternatives like unsplash_topic_photos or unsplash_search_users. The read-only hint and attribution advice provide some context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds valuable context beyond the annotations: the authentication requirement, the setup command, and the fact that the target collection must belong to the authenticated user. 'Not read-only' is consistent with the annotations, with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action, and includes the prerequisite without excessive detail. The phrase 'Not read-only' is slightly redundant with the annotations, but it does not meaningfully hurt conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity—two required string parameters, full schema coverage, and annotations covering safety—the description is largely complete. It covers what the tool does, which collections are valid, and what the agent must do before invoking it. It does not describe duplicate-add behavior or exact return shape, but these are not essential for this operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so id and photo_id are already well documented. The description adds useful semantic context by clarifying that the collection ID must reference a collection owned by the authenticated user, which also reinforces the need for OAuth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Add a photo to a collection') and states the critical ownership scope ('owned by the authenticated user'). This allows an agent to distinguish it from read-only collection tools and from the sibling remove_photo_from_collection without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the prerequisite: OAuth sign-in, with the exact CLI command to run first. It does not explicitly mention when-not-to-use or name alternatives, but the add-vs-remove context and the auth requirement give sufficient situational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint; the description reinforces 'Read-only' and adds behavioral details: pagination, attribution, and imgix URL customization. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, followed by actionable detail. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated list tool with 4 parameters and no output schema, the description covers purpose, pagination, return format (URLs, sizes, attribution), and usage of raw URL. It equips the 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing baseline 3. The description adds meaningful context about return values (imgix URLs, fixed sizes, attribution) and pagination, going beyond individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists photos in a collection, with pagination, URLs, and attribution. It distinguishes itself from sibling tools that focus on users, topics, or stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does and how to use the output URLs, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., when to use unsplash_collection_photos vs unsplash_topic_photos). No exclusions or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly and openWorld hints; the description reinforces read-only behavior and additionally documents what the response contains: raw imgix URL, appended customization params, and fixed size variants. This adds useful behavioral detail 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the action, and every clause adds value. The raw URL example is practical and concise, providing exactly the customization guidance an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one required parameter and no output schema, the description sufficiently covers input and output: ID/slug lookup, returned detail/URLs, attribution, and available image variants. An agent can invoke the tool and interpret the response correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes 'id' as 'The Unsplash photo ID or slug.' The description repeats this same information and does not add new parameter-level semantics, so it stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific operation: get a single Unsplash photo by ID or slug, with full detail and URLs. It also distinguishes itself from sibling tools like list_photos, search_photos, and random_photo by emphasizing lookup of one specific photo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys the main usage context: use when you have a known photo ID or slug and need that photo's detail. It does not explicitly name alternatives or exclusion conditions, but the 'single photo by ID/slug' framing makes the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds authentication requirements and ownership constraints beyond the annotations, telling the agent that OAuth sign-in is required and that only collections owned by the user are affected. It also explicitly confirms the operation is not read-only, which aligns with readOnlyHint=true. It does not describe reverse effects or error cases, but the annotations already cover the basic safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the action, and every sentence adds useful context: what the tool does, the OAuth prerequisite, and the non-read-only nature. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple two-parameter mutation with no nested objects and no output schema. The schema fully explains both parameters, and the description covers the operational prerequisites and ownership constraint. The agent has enough 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'id' and 'photo_id' clearly documented in the schema. The description does not need to explain parameters further. It reaches the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Remove'), the resource ('photo from a collection'), and the ownership scope ('owned by the authenticated user'). This clearly distinguishes it from related operations like adding a photo to a collection or deleting a collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it is for authenticated users removing photos from their own collections, and it explicitly states the OAuth prerequisite with a concrete login command. It does not explicitly name alternatives or when-not-to-use scenarios, so it falls slightly short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description augments the readOnlyHint by specifying paginated output and the compact field set, which is valuable because there is no output schema. It repeats 'read-only,' but the return representation and pagination behavior add meaningful transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, dense sentences with no filler. The purpose is front-loaded and the return behavior is stated immediately afterward, making it easy for an agent to scan and use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only search tool, this description provides a clear contract: keyword input, paginated output, and the returned fields. Combined with fully documented parameters and readOnlyHint, an agent has enough context to call it correctly without extra inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameter meaning is already fully documented in the input schema. The description's phrases 'keyword' and 'paginated' loosely correspond to query and page/per_page, but they do not add significant semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Search Unsplash collections by keyword.' It also says exactly what is returned (paginated compact collections with title, description, cover photo, curator), which distinguishes it from plain collection listing and other search variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Search by keyword' gives clear context for when to use the tool, especially against the backdrop of sibling tools like list collections or fetching single collections. It does not explicitly name an alternative or say when not to use it, but the intended usage is easy to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description reinforces read-only behavior and adds context about specific data returned, enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus 'Read-only,' front-loading the core action and scope without extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides example outputs (new photos, downloads, views), which is adequate given the tool's simplicity and lack of output schema. It covers the essential behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. The description appropriately omits parameter details, as none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves Unsplash-wide totals for the past 30 days, listing example metrics (new photos, downloads, views). This distinguishes it from siblings like unsplash_total_stats, which likely provides all-time data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates read-only usage and implies temporal scope (past 30 days). While it doesn't explicitly contrast with unsplash_total_stats, the name and description are sufficient for an agent to infer when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, and the description is consistent with them, adding real behavioral value beyond the annotations: the partial-update semantics 'Only the fields you pass are changed' informs the agent this is PATCH-like behavior rather than replace-all, and the explicit OAuth login prerequisite surfaces a likely failure mode. The redundant fragment 'Not read-only.' restates what readOnlyHint=false already conveys, which prevents this from reaching a 5. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient and front-loaded: the main purpose comes first, the critical partial-update semantics second, and the auth prerequisite last. Every clause earns its place except the final 'Not read-only.' fragment, which duplicates the information already carried by readOnlyHint=false in the annotations — a minor redundancy. The login command with an example adds legitimate practical value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 4 simple parameters, one required, and a full schema, the description covers everything an dimension agent needs to call it correctly: the purpose, the ownership scope, the partial-update field-behavior, and the only prerequisite (OAuth login). No output schema exists, but none is strictly necessary for a straightforward update tool whose success is simply the persisted changes. No equivalent gaps like on boarding the no-op failure modes that the auth hint already covers.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3 — each parameter (id, title, private, description) is already documented in the schema. The description adds meaningful semantic context beyond that: by stating 'Only the param fields you pass are changed,' it tells the agent that title, private, and description are optional partial updates and that omitting them is safe, which is not explicitly stated in the schema itself. This enrichment raises it one rung above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource combination: 'Update a collection owned by the authenticated user.' The ownership constraint differentiates it from sibling tools like unsplash_create_collection, unsplash_delete_collection, and other update tools (unsplash_update_photo, unsplash_update_my_profile) with no ambiguity. The scope qualifier 'owned by the authenticated user' also tells an agent this only applies to the user's own collections, which is a meaningful restriction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use it: editing a user's own existing collection, including the explicit prerequisite 'Requires OAuth sign-in — run npx @hanoak/unsplash-mcp-server login first.' The ownership wording implies the exclusion (you cannot update collections you don't own), but it doesn't explicitly name a sibling alternative or state a when-not-to-use case. A clear operational trigger with prerequisites is present, so this falls short of the full 5 which requires explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses pagination, compact response objects, 'ready-to-use attribution', a raw imgix URL with query-param customization, and fixed sizes — valuable behavior beyond the readOnlyHint. The 'Read-only' statement aligns with the annotations, and the extra return-shape detail carries meaningful weight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused sentences: purpose first, then compact response shape and attribution, then the practical imgix URL customization hint. Every sentence earns its place and 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must carry return-shape details — and it does, including the raw/full/regular/small/thumb variants. Combined with schema-documented parameters, an agent has enough to select this tool and interpret its result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both page and per_page, including defaults and clamping behavior. The description only reinforces 'paginated' without adding new semantic detail, so a baseline 3 is appropriate at 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with 'List the latest featured Unsplash photos (paginated)' — a specific verb, resource, and scope. This clearly distinguishes it from sibling tools like unsplash_random_photo, unsplash_search_photos, and unsplash_user_photos without needing to inspect their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'latest featured photos (paginated)' gives a clear context for when to use this tool: browsing the curated Unsplash feed page by page. It does not explicitly name when-not-to-use it or direct users to a sibling tool, so it misses the top bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses valuable behavior: content safety defaults to 'high', returned data includes ready-to-use attribution, and a raw imgix base URL is provided for custom resizing/formatting. This gives an agent operational expectations beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense: it front-loads the core behavior, lists filters in one short sentence, summarizes the response shape, and explains a key URL recipe in a single example. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates well by explaining exactly what the agent will receive: URLs, dimensions, color, attribution, and fixed/raw image size options. Optional parameters are clear, and the tool's random selection purpose is fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented. The description restates the filter dimensions but adds no new semantic meaning about the parameters that is not already in the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Fetch a single random photo'), the resource (Unsplash), and optional refinement dimensions (search term, orientation, collections, topics, user). This clearly distinguishes it from sibling tools like unsplash_list_photos or unsplash_search_photos, which do not return a single random photo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the use case obvious: you need one random photo, optionally filtered by criteria. It does not explicitly name alternative tools or exclusion conditions, but the 'random' framing and mention of optional narrowing filters are a clear context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses useful behavioral details: output is paginated; photos include compact URLs and attribution; content_filter defaults to 'high' safety; and each photo has a raw imgix base URL with appendable parameters plus fixed sizes. This is meaningful context that helps an agent understand what will happen and what to pass on.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, front-loaded with the core action, and uses every sentence to add value: the keyword search, the filter list, the return shape, the default safety behavior, the read-only nature, and the imgix URL detail. There is no filler or repetition beyond the mention of the content filter default.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema (100% coverage) and the absence of an output schema, the description sufficiently fills the gap by describing the output: paginated compact photos, URLs, attribution, imgix URL customization, and fixed sizes. An agent has enough information to select the tool, set required and optional parameters, and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameter semantics are already fully documented. The description adds a general overview of filters and reiterates the high content-filter default, but does not provide additional meaning for individual parameters beyond what the input schema contains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Search Unsplash photos by keyword.' It then lists the optional filters and return format, which distinguishes it clearly from sibling search tools like unsplash_search_collections and unsplash_search_users. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes the tool's use case: searching photos by keyword with optional filters. It provides enough context an agent needs to choose this tool, though it does not explicitly name alternatives or state when not to use it. The context is clear, but exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds meaningful behavioral context beyond them: it exposes that private fields are included, that OAuth sign-in is required, and the exact login command. It also reinforces read-only behavior without contradicting any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no fluff. The core action and unique scope are front-loaded, and the prerequisite and read-only note are placed after the main purpose. Every sentence adds needed information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, self-profile retrieval tool, the description is adequately complete. It explains what is returned (private fields like email and remaining uploads), what is required (OAuth login), and the safety profile (read-only). With annotations and an empty schema, nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters and an empty schema, so there are no parameter details needed. The baseline for 0 parameters is 4, and the description does not need to compensate for any parameter coverage gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a precise resource ('the authenticated user's own Unsplash profile'), and important scope details ('including private fields (email, remaining uploads)'). The word 'own' clearly distinguishes it from the sibling unsplash_get_user, which retrieves another user's profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the usage context clear: it is for the authenticated user's own profile, and it gives a concrete prerequisite ('run npx @hanoak/unsplash-mcp-server login first'). However, it does not explicitly state when not to use it or name alternatives, although 'own' and the sibling list make that inference easy.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly discloses the side effect (downloads are counted toward the photographer's stats) and explicitly warns it is NOT read-only, which aligns with annotations readOnlyHint=false. It also adds non-obvious behavior: it returns a fresh, usable image download URL. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and well-structured: it states the purpose, the required input, the return value, and the critical side-effect warning in four purposeful sentences. Nothing is redundant or unnecessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter side-effectful operation, this is complete. It explains why it exists, when and how to call it, what it returns, and what the consequences are. No important contextual gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the single parameter with clear guidance at 100% coverage. The description repeats the same instruction about passing the download_location URL, adding no substantial new semantic information beyond the schema, so a baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Register a download'), the exact resource (a photo download), and the triggering condition (actually used/displayed). This distinguishes it from all sibling tools, which cover listing, searching, and modifying photos or collections, not tracking downloads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains when to call the tool — on actual use/display per Unsplash API guidelines — and when not to call it: only on real use, because it is not read-only. It also tells the agent to pass the download_location from a prior photo result, fully specifying the required context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![unsplash-mcp-server MCP server](https://glama.ai/mcp/servers/hanoak/unsplash-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/hanoak/unsplash-mcp-server)

Score Badge

Copy to your README.md:

[![unsplash-mcp-server MCP server](https://glama.ai/mcp/servers/hanoak/unsplash-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/hanoak/unsplash-mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hanoak/unsplash-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server