A
licenseNot graded
qualityD
maintenanceAn MCP server implementation that enables users to search, download Freepik resources, and generate images using Mystic AI through natural language requests.
3
JavaScript
MIT
Freepik FastMCP Toolkit
OfficialUtilizes .env files for secure storage of API keys and other sensitive configuration data, preventing accidental exposure of credentials.
Provides direct integration with Freepik's APIs for searching and downloading icons in multiple formats, managing multimedia content resources, classifying images using AI, and generating custom images through Mystic AI.
Supports Git-based workflow for contributions, including feature branching, conventional commits, and pull request submissions.
Enables GitHub-based collaboration through pull requests, issue tracking for troubleshooting, and repository-based contribution workflow.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Freepik FastMCP Toolkitsearch for business icons with blue color scheme"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Freepik MCP
🚀 MCP Server for seamless Freepik API integration
🎯 What is this?
A Model Context Protocol (MCP) server that connects your AI assistants (Claude, Cursor, etc.) directly with Freepik's powerful APIs. Generate, search, and manage visual content without leaving your AI workflow.
Related MCP server: Freepik MCP
🛠️ What tools are available?
🎨 Icon Search & Download - Find and download icons in multiple formats
📁 Resource Management - Access and manage multimedia content
🤖 AI Image Classification - Automatically classify and analyze images
🖼️ Image Generation - Create custom images using Mystic AI
📋 Prerequisites
Before you start, make sure you have:
Python 3.12+ installed
uv dependency manager (install here)
Freepik API Key (get yours here)
🚀 Installation
1. Clone and navigate
git clone <REPOSITORY_URL>
cd freepik-mcp2. Install using Makefile
# Install dependencies
make install
# Verify installation
make version3. Configure your API Key
echo "FREEPIK_API_KEY=your_api_key_here" > .env💡 Get your API Key at: freepik.com/api
⚙️ Configuration for AI Assistants
For Claude Desktop or Cursor on Linux
Add this to your config.json file:
⚠️ For Windows users: If you're on Windows, you need to use WSL (Windows Subsystem for Linux) to run this MCP server.
{
"mcpServers": {
"freepik-fastmcp": {
"command": "uv",
"args": [
"run",
"--directory",
"/FULL/PATH/TO/freepik-mcp",
"main.py"
],
"env": {
"FREEPIK_API_KEY": "your_actual_api_key_here"
}
}
}
}🔧 Important Configuration Steps
Find your full path:
pwd # Copy the output and replace /FULL/PATH/TO/ in the configReplace with your API key:
Get it from freepik.com/api
Replace
your_actual_api_key_here
🏃♂️ Quick Start
# Development mode (auto-reload)
make dev
# Production mode
make run
# Check code quality
make lint
# Format code
make format
# Clean temporary files
make clean
# See all commands
make help🤝 Contributing
We welcome contributions! Please follow these guidelines:
📝 Commit Convention
This project uses Conventional Commits. Format your commits as:
<type>(<scope>): <description>
[optional body]
[optional footer(s)]Types:
feat: New featurefix: Bug fixdocs: Documentation changesstyle: Code style changes (formatting, etc.)refactor: Code refactoringtest: Adding or updating testschore: Maintenance tasks
Examples:
feat(icons): add search filtering by category
fix(api): resolve authentication timeout issue
docs(readme): update installation instructions
refactor(mystic): improve error handling logic🔄 Contribution Workflow
Fork the repository
Create a feature branch:
git checkout -b feat/amazing-featureCommit using conventional format:
git commit -m "feat: add amazing feature"Push to your branch:
git push origin feat/amazing-featureOpen a Pull Request
📚 Development Commands
Command | Description |
| Show all available commands |
| Install dependencies |
| Run in development mode |
| Run in production mode |
| Check code quality |
| Format code automatically |
| Clean temporary files |
| Check FastMCP version |
🛡️ Security
⚠️ Never commit your API Key
✅ Use
.envfiles for sensitive data✅ The
.envfile is in.gitignore
📖 API Documentation
For detailed API information:
🆘 Troubleshooting
Common issues:
"Command not found" → Install
uvdependency manager"Invalid API Key" → Check your key at freepik.com/api
"Path not found" → Verify the full path in your config
"Connection refused" → Make sure the server is running with
make dev
Still having issues? Open an issue on GitHub with:
Your OS and Python version
Full error message
Configuration file (without API key)
Ready to create amazing content with AI? 🎨✨
Available Tools
9 toolsdetect_ai_imageC
Accepts an image file as input and analyzes it to determine the probability that the image was generated by artificial intelligence, providing a confidence score.
Responses:
200 (Success): OK - The request has succeeded, and the image has been classified.
Content-Type:
application/jsonResponse Properties:
Example:
{
"data": [
{
"probability": 0.9489172697067261,
"class_name": "not_ai"
},
{
"probability": 0.9489172697067261,
"class_name": "not_ai"
}
]
}400: Bad Request - The server could not understand the request due to invalid syntax.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}401: Unauthorized - The client must authenticate itself to get the requested response.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}500: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Internal Server Error"
}503: Service Unavailable
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Service Unavailable. Please try again later."
}ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image | No |
TDQS
C2.6/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers limited behavioral insight. It mentions authentication requirements (401 response) and error conditions, but lacks details on rate limits, processing time, model accuracy, or what constitutes a valid image. The HTTP response documentation adds some value but doesn't fully compensate for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is poorly structured with excessive HTTP response documentation that belongs in an output schema. The core purpose is buried under verbose response examples, making it inefficient for quick understanding. The response section adds unnecessary bulk without corresponding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, 0% schema coverage, and no output schema, the description is incomplete. It lacks crucial details about parameter constraints, performance characteristics, accuracy limitations, and practical usage considerations needed for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the single parameter 'image' beyond what's in the schema. It doesn't explain acceptable image formats, size limits, or quality requirements, leaving significant gaps in parameter understanding.
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 purpose with specific verb ('analyzes') and resource ('image file'), explaining it determines AI generation probability with a confidence score. It distinguishes itself from sibling tools like text_to_image_mystic_sync by focusing on detection rather than generation.
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?
No explicit guidance on when to use this tool versus alternatives is provided. The description doesn't mention prerequisites, limitations, or comparison with other tools, leaving the agent without context for appropriate tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
download_icon_by_idB
Download the specified icon by its unique ID in the requested format and size.
Path Parameters:
id (Required): Icon resource ID
Query Parameters:
format: These are the formats available for download
Note: gif, mp4, aep, json, psd and eps are not available for standard and sticker icon types.
png_size: These are the sizes available for png_url formats.
Note: Only apply to format png.
Responses:
200 (Success): OK
Content-Type:
application/jsonResponse Properties:
Example:
{
"data": {
"filename": "filename",
"url": "https://openapi-generator.tech"
}
}400: Bad Request - The server could not understand the request due to invalid syntax.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}401: Unauthorized - The client must authenticate itself to get the requested response.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}403: Forbidden - The client does not have permission to access the requested resource.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}404: Not Found - The server can not find the requested resource.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}429: Too Many Requests - The client has sent too many requests in a given amount of time.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}500: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Internal Server Error"
}ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| Accept-Language | No | Specifies the search query language using the ISO 639-1 (2-letter language code) and the ISO 3166-1 (2-letter country code) for language variants. The API will use "en-US" as a default language for processing if a code is not provided, or does not exist. | |
| id | Yes | Icon resource ID | |
| format | No | These are the formats available for download - Note: gif, mp4, aep, json, psd and eps are not available for standard and sticker icon types. | |
| png_size | No | These are the sizes available for png_url formats. - Note: Only apply to format png. |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds some context beyond basic purpose, such as format restrictions for certain icon types and size applicability for PNG, but lacks details on authentication needs, rate limits, or what the download entails (e.g., file retrieval vs. metadata). No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is overly verbose and poorly structured, including extensive HTTP response details that are not needed for an AI agent. It mixes tool description with API documentation, making it front-loaded with useful info but cluttered with redundant sections like full error examples, which reduces clarity and efficiency.
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 no annotations and no output schema, the description partially compensates by including format/size constraints and response examples, but it's incomplete for a download tool. It misses key behavioral aspects like authentication requirements or download mechanics, and the verbose structure detracts from providing a clear, complete overview.
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 the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema, such as repeating format and size notes, but doesn't provide additional semantic context like usage examples or edge cases. Baseline 3 is appropriate given high 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 clearly states the tool's purpose with specific verb ('Download') and resource ('icon by its unique ID'), and distinguishes it from siblings like 'get_icon_detail_by_id' (which retrieves metadata) and 'download_resource_by_id' (which downloads resources, not specifically icons). The mention of 'requested format and size' further specifies the action.
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?
No explicit guidance on when to use this tool versus alternatives is provided. While the purpose implies it's for downloading icons, it doesn't differentiate from 'download_resource_by_id' or explain when to choose one over the other. The description lacks context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
download_resource_by_idC
Download a specific resource by providing the resource ID. This endpoint supports downloading various types of resources including vectors, PSDs, photos, and AI-generated content.
Path Parameters:
resource-id (Required): Photo, video or PSD resource ID
Query Parameters:
image_size: Resizes the photo to a specified size while maintaining aspect ratio. Accepts a pixel value (100px to 2000px) or keywords small(1000px), medium(1500px), large(2000px), original corresponding to standard website sizes. The size depends on the image orientation, the longest side of the image will be resized to the specified size. If not specified, the highest resolution is provided. Applicable only to photos.
Responses:
200 (Success): OK Response
Content-Type:
application/jsonResponse Properties:
Example:
{
"data": {
"signed_url": "https://img.freepik.com/premium-photo/close-up-cat-resting_1048944-9269194.jpg?t=st=1725276607~exp=1725280207~hmac=1538f1b294fc3a19a19e9f02ceeb6594a9a1e36a900de85d47bbd386e27dddbe",
"filename": "blackboard-template.zip",
"url": "https://downloadscdn5.freepik.com/d/1137445/blackboard-template.zip"
}
}400: Bad Request - The server could not understand the request due to invalid syntax.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}401: Unauthorized - The client must authenticate itself to get the requested response.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}403: Forbidden - The client does not have permission to access the requested resource.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}404: Not Found - The server can not find the requested resource.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}429: Too Many Requests - The client has sent too many requests in a given amount of time.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}500: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Internal Server Error"
}503: Service Unavailable
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Service Unavailable. Please try again later."
}ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| resource-id | Yes | Photo, video or PSD resource ID | |
| Accept-Language | No | Specifies the search query language using the ISO 639-1 (2-letter language code) and the ISO 3166-1 (2-letter country code) for language variants. The API will use "en-US" as a default language for processing if a code is not provided, or does not exist. | |
| image_size | No | Resizes the photo to a specified size while maintaining aspect ratio. Accepts a pixel value (100px to 2000px) or keywords small(1000px), medium(1500px), large(2000px), original corresponding to standard website sizes. The size depends on the image orientation, the longest side of the image will be resized to the specified size. If not specified, the highest resolution is provided. Applicable only to photos. |
TDQS
C2.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the resource types supported (vectors, PSDs, photos, AI-generated content) and includes HTTP response codes with examples, which adds behavioral context like authentication needs (401), rate limits (429), and error handling. However, it lacks details on permissions, side effects, or performance characteristics, leaving gaps for a mutation-like download operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is overly verbose and poorly structured. It includes extensive HTTP response details that belong in an output schema or annotations, not in the description. The first two sentences are front-loaded, but the bulk is redundant parameter info and response examples, making it inefficient and cluttered.
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 no annotations and no output schema, the description compensates by including response codes and examples, which helps understand behavior. However, for a download tool with 3 parameters and mutation-like effects, it should better explain side effects, return values, and usage context. It's minimally adequate but has clear gaps in 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?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description repeats parameter details in the 'Path Parameters' and 'Query Parameters' sections, adding no new semantic meaning beyond what's in the schema. This meets the baseline of 3, as the schema does the heavy lifting without extra value from the description.
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 the tool's purpose: 'Download a specific resource by providing the resource ID' with a verb ('download') and resource ('resource'). It distinguishes from siblings like 'get_resource_detail_by_id' (which retrieves metadata) and 'download_icon_by_id' (which is icon-specific). However, it doesn't explicitly contrast with all siblings, keeping it at 4 rather than 5.
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. It doesn't mention siblings like 'get_resource_download_formats' (which might list formats before download) or 'download_icon_by_id' (for icons specifically). There's no context about prerequisites or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_icon_detail_by_idC
Get detailed information about a specific icon identified by its unique ID.
Path Parameters:
id (Required): Icon resource ID
Responses:
200 (Success): OK
Content-Type:
application/jsonResponse Properties:
Example:
{
"data": {
"free_svg": true,
"related": {
"visual_concept": [
{
"free_svg": true,
"created": "2023-03-07T23:05:26Z",
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "a woman reads a book in a tablet sits in the luxurious back of the library",
"style": {
"name": "Meticulous Yellow shadow",
"id": 50
},
"id": 52912,
"family": {
"total": 1200,
"name": "Outline",
"id": 1
},
"thumbnails": [
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
},
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
}
],
"slug": "a-woman-reads-a-book-in-a-tablet-sits-in-the-luxurious-back-of-the-library"
},
{
"free_svg": true,
"created": "2023-03-07T23:05:26Z",
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "a woman reads a book in a tablet sits in the luxurious back of the library",
"style": {
"name": "Meticulous Yellow shadow",
"id": 50
},
"id": 52912,
"family": {
"total": 1200,
"name": "Outline",
"id": 1
},
"thumbnails": [
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
},
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
}
],
"slug": "a-woman-reads-a-book-in-a-tablet-sits-in-the-luxurious-back-of-the-library"
}
],
"style": [
{
"free_svg": true,
"created": "2023-03-07T23:05:26Z",
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "a woman reads a book in a tablet sits in the luxurious back of the library",
"style": {
"name": "Meticulous Yellow shadow",
"id": 50
},
"id": 52912,
"family": {
"total": 1200,
"name": "Outline",
"id": 1
},
"thumbnails": [
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
},
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
}
],
"slug": "a-woman-reads-a-book-in-a-tablet-sits-in-the-luxurious-back-of-the-library"
},
{
"free_svg": true,
"created": "2023-03-07T23:05:26Z",
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "a woman reads a book in a tablet sits in the luxurious back of the library",
"style": {
"name": "Meticulous Yellow shadow",
"id": 50
},
"id": 52912,
"family": {
"total": 1200,
"name": "Outline",
"id": 1
},
"thumbnails": [
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
},
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
}
],
"slug": "a-woman-reads-a-book-in-a-tablet-sits-in-the-luxurious-back-of-the-library"
}
],
"variants": [
{
"free_svg": true,
"created": "2023-03-07T23:05:26Z",
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "a woman reads a book in a tablet sits in the luxurious back of the library",
"style": {
"name": "Meticulous Yellow shadow",
"id": 50
},
"id": 52912,
"family": {
"total": 1200,
"name": "Outline",
"id": 1
},
"thumbnails": [
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
},
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
}
],
"slug": "a-woman-reads-a-book-in-a-tablet-sits-in-the-luxurious-back-of-the-library"
},
{
"free_svg": true,
"created": "2023-03-07T23:05:26Z",
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "a woman reads a book in a tablet sits in the luxurious back of the library",
"style": {
"name": "Meticulous Yellow shadow",
"id": 50
},
"id": 52912,
"family": {
"total": 1200,
"name": "Outline",
"id": 1
},
"thumbnails": [
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
},
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
}
],
"slug": "a-woman-reads-a-book-in-a-tablet-sits-in-the-luxurious-back-of-the-library"
}
]
},
"created": "2023-03-07T23:05:26Z",
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "a woman reads a book in a tablet sits in the luxurious back of the library",
"style": {
"name": "Meticulous Yellow shadow",
"id": 50
},
"id": 52912,
"family": {
"total": 1200,
"name": "Outline",
"id": 1
},
"thumbnails": [
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
},
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
}
],
"slug": "a-woman-reads-a-book-in-a-tablet-sits-in-the-luxurious-back-of-the-library",
"tags": [
{
"name": "Dog",
"slug": "dog"
},
{
"name": "Dog",
"slug": "dog"
}
]
}
}400: Bad Request - The server could not understand the request due to invalid syntax.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}401: Unauthorized - The client must authenticate itself to get the requested response.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}404: Not Found - The server can not find the requested resource.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}500: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Internal Server Error"
}ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| Accept-Language | No | Specifies the search query language using the ISO 639-1 (2-letter language code) and the ISO 3166-1 (2-letter country code) for language variants. The API will use "en-US" as a default language for processing if a code is not provided, or does not exist. | |
| id | Yes | Icon resource ID |
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions HTTP response codes (200, 400, 401, 404, 500) and includes an example response, but lacks critical details like authentication needs, rate limits, whether it's a read-only operation, or any side effects. The example response is overly verbose and repetitive, adding noise rather than clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is poorly structured and excessively long due to the inclusion of a massive, repetitive JSON example that duplicates data unnecessarily. The core information is buried under verbose examples, making it difficult to parse quickly. A more concise approach would focus on key details without redundant examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (retrieving detailed icon data) and the absence of annotations and output schema, the description is incomplete. It lacks information on authentication, rate limits, error handling specifics beyond HTTP codes, and how to interpret the response structure efficiently. The verbose example doesn't compensate for these gaps.
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 the schema already fully documents both parameters ('id' and 'Accept-Language'). The description adds a brief mention of the 'id' parameter in the 'Path Parameters' section but doesn't provide additional semantic context beyond what's in the schema. This meets the baseline for high schema coverage.
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 the tool's purpose as 'Get detailed information about a specific icon identified by its unique ID,' which is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'get_resource_detail_by_id' or 'search_icons,' which appear to serve related but distinct purposes.
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. It doesn't mention sibling tools like 'get_resource_detail_by_id' for non-icon resources or 'search_icons' for browsing, nor does it specify prerequisites such as authentication requirements or rate limits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_resource_detail_by_idC
Retrieve the detailed information of a specific resource by its ID. This endpoint supports multiple resource types including PSD, vector, photo, and AI-generated content.
Path Parameters:
resource-id (Required): Photo, video or PSD resource ID
Responses:
200 (Success): OK Response
Content-Type:
application/jsonResponse Properties:
Example:
{
"data": {
"preview": {
"width": 300,
"url": "https://www.freepik.com/free-ai-image/surreal-landscape_41357833.htm",
"height": 500
},
"new": true,
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"created": "2023-03-07T23:05:26Z",
"available_formats": {
"psd": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"jpg": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"zip": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"fonts": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"svg": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"ai": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"png": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"eps": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"resources": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"3d-render": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"atn": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
}
},
"type": "photo",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm",
"license": "https://www.freepik.com/profile/license/pdf/4350594",
"premium": true,
"is_ai_generated": true,
"related_resources": {
"suggested": [
{
"preview": {
"width": 300,
"url": "https://www.freepik.com/free-ai-image/surreal-landscape_41357833.htm",
"height": 500
},
"new": true,
"premium": true,
"is_ai_generated": true,
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "White t-shirt with copy space on gray background",
"id": 15667327,
"type": "vector",
"has_prompt": true,
"slug": "merry-christmas",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
},
{
"preview": {
"width": 300,
"url": "https://www.freepik.com/free-ai-image/surreal-landscape_41357833.htm",
"height": 500
},
"new": true,
"premium": true,
"is_ai_generated": true,
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "White t-shirt with copy space on gray background",
"id": 15667327,
"type": "vector",
"has_prompt": true,
"slug": "merry-christmas",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
}
],
"same_author": [
{
"preview": {
"width": 300,
"url": "https://www.freepik.com/free-ai-image/surreal-landscape_41357833.htm",
"height": 500
},
"new": true,
"premium": true,
"is_ai_generated": true,
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "White t-shirt with copy space on gray background",
"id": 15667327,
"type": "vector",
"has_prompt": true,
"slug": "merry-christmas",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
},
{
"preview": {
"width": 300,
"url": "https://www.freepik.com/free-ai-image/surreal-landscape_41357833.htm",
"height": 500
},
"new": true,
"premium": true,
"is_ai_generated": true,
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "White t-shirt with copy space on gray background",
"id": 15667327,
"type": "vector",
"has_prompt": true,
"slug": "merry-christmas",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
}
],
"same_collection": {
"items": [
{
"preview": {
"width": 300,
"url": "https://www.freepik.com/free-ai-image/surreal-landscape_41357833.htm",
"height": 500
},
"new": true,
"premium": true,
"is_ai_generated": true,
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "White t-shirt with copy space on gray background",
"id": 15667327,
"type": "vector",
"has_prompt": true,
"slug": "merry-christmas",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
},
{
"preview": {
"width": 300,
"url": "https://www.freepik.com/free-ai-image/surreal-landscape_41357833.htm",
"height": 500
},
"new": true,
"premium": true,
"is_ai_generated": true,
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "White t-shirt with copy space on gray background",
"id": 15667327,
"type": "vector",
"has_prompt": true,
"slug": "merry-christmas",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
}
],
"url": "https://www.freepik.com/collection/shining"
},
"same_series": {
"items": [
{
"preview": {
"width": 300,
"url": "https://www.freepik.com/free-ai-image/surreal-landscape_41357833.htm",
"height": 500
},
"new": true,
"premium": true,
"is_ai_generated": true,
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "White t-shirt with copy space on gray background",
"id": 15667327,
"type": "vector",
"has_prompt": true,
"slug": "merry-christmas",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
},
{
"preview": {
"width": 300,
"url": "https://www.freepik.com/free-ai-image/surreal-landscape_41357833.htm",
"height": 500
},
"new": true,
"premium": true,
"is_ai_generated": true,
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "White t-shirt with copy space on gray background",
"id": 15667327,
"type": "vector",
"has_prompt": true,
"slug": "merry-christmas",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
}
],
"url": "https://www.freepik.com/serie/32689488"
}
},
"name": "White t-shirt with copy space on gray background",
"id": 15667327,
"has_prompt": true,
"download_size": 1024,
"slug": "merry-christmas",
"related_tags": [
{
"name": "Merry Christmas",
"slug": "merry-christmas",
"url": "https://www.freepik.com/dog"
},
{
"name": "Merry Christmas",
"slug": "merry-christmas",
"url": "https://www.freepik.com/dog"
}
],
"dimensions": {
"width": 2000,
"height": 3000
}
}
}400: Bad Request - The server could not understand the request due to invalid syntax.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}401: Unauthorized - The client must authenticate itself to get the requested response.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}404: Not Found - The server can not find the requested resource.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}500: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Internal Server Error"
}503: Service Unavailable
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Service Unavailable. Please try again later."
}ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| resource-id | Yes | Photo, video or PSD resource ID | |
| Accept-Language | No | Specifies the search query language using the ISO 639-1 (2-letter language code) and the ISO 3166-1 (2-letter country code) for language variants. The API will use "en-US" as a default language for processing if a code is not provided, or does not exist. |
TDQS
C2.8/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the tool 'supports multiple resource types' and includes HTTP response codes with examples, which adds some context. However, it doesn't disclose critical behavioral traits like authentication requirements, rate limits, whether it's idempotent, or error handling specifics beyond status codes. For a read operation with no annotation coverage, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is excessively long and poorly structured for an AI agent. It front-loads the purpose but then includes massive JSON response examples (over 200 lines) that belong in an output schema, not a description. The 'Path Parameters' section duplicates schema information. While comprehensive, it violates conciseness principles by including implementation details that don't help an agent select or invoke the tool correctly.
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 no annotations and no output schema, the description attempts to compensate with extensive response examples and error codes. However, this creates information overload rather than targeted completeness. It covers response formats but misses behavioral context like authentication needs. For a read operation with 2 parameters, it's partially complete but inefficiently organized, mixing tool selection guidance with implementation details.
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 the schema already documents both parameters thoroughly. The description adds minimal parameter semantics beyond the schema: it repeats the resource-id requirement in a 'Path Parameters' section but doesn't provide additional context about ID formats or examples. The Accept-Language parameter isn't mentioned in the description at all. With high schema coverage, baseline 3 is appropriate as the description adds little value over the structured schema.
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 the tool's purpose: 'Retrieve the detailed information of a specific resource by its ID' with specific resource types listed (PSD, vector, photo, AI-generated content). It distinguishes from siblings like search_resources (which searches) and download_resource_by_id (which downloads), but doesn't explicitly contrast them. The verb 'retrieve' and resource specificity are clear, though sibling differentiation is implicit rather than explicit.
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 explicit guidance on when to use this tool versus alternatives. While it mentions resource types, it doesn't indicate when to choose this over get_icon_detail_by_id for icons, or when detailed info is needed versus download_resource_by_id for downloading. No prerequisites, exclusions, or alternative scenarios are mentioned, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_resource_download_formatsC
Retrieve a resource by specifying both the resource ID and the format. This endpoint allows for precise downloading of resources in the desired format.
Path Parameters:
resource-id (Required): Photo, video or PSD resource ID
resource-format (Required): Resource format
Responses:
200 (Success): OK
Content-Type:
application/jsonResponse Properties:
Example:
{
"data": [
{
"signed_url": "https://img.freepik.com/premium-photo/close-up-cat-resting_1048944-9269194.jpg?t=st=1725276607~exp=1725280207~hmac=1538f1b294fc3a19a19e9f02ceeb6594a9a1e36a900de85d47bbd386e27dddbe",
"filename": "blackboard-template.zip",
"url": "https://downloadscdn5.freepik.com/d/1137445/blackboard-template.zip"
},
{
"signed_url": "https://img.freepik.com/premium-photo/close-up-cat-resting_1048944-9269194.jpg?t=st=1725276607~exp=1725280207~hmac=1538f1b294fc3a19a19e9f02ceeb6594a9a1e36a900de85d47bbd386e27dddbe",
"filename": "blackboard-template.zip",
"url": "https://downloadscdn5.freepik.com/d/1137445/blackboard-template.zip"
}
]
}400: Bad Request - The server could not understand the request due to invalid syntax.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}401: Unauthorized - The client must authenticate itself to get the requested response.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}403: Forbidden - The client does not have permission to access the requested resource.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}404: Not Found - The server can not find the requested resource.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}429: Too Many Requests - The client has sent too many requests in a given amount of time.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}500: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Internal Server Error"
}ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| resource-id | Yes | Photo, video or PSD resource ID | |
| resource-format | Yes | Resource format |
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions the tool retrieves/downloads resources and includes HTTP response codes (e.g., 200, 400, 429), it lacks critical behavioral details: it doesn't specify authentication requirements, rate limits beyond the 429 error mention, whether it's read-only or mutative, what happens on success (e.g., returns signed URLs), or any side effects. The description is insufficient for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is poorly structured and verbose. It starts with a clear purpose statement but then includes extensive, redundant HTTP response documentation (e.g., multiple error codes with examples) that belongs in an output schema or annotations, not in the description. This bloats the text without adding helpful guidance for tool selection, making it inefficient and not front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete for a tool with 2 parameters. It lacks essential context: no explanation of return values (though the 200 response example shows data with URLs, this isn't clarified in the description text), no behavioral traits like auth needs or rate limits, and no differentiation from siblings. The HTTP error details don't compensate for these gaps, making it inadequate for informed tool use.
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 the schema fully documents both parameters ('resource-id' and 'resource-format') with descriptions and enum values. The description adds minimal value beyond the schema, only restating that parameters are required for precise downloading. No additional syntax, format details, or examples are provided in the description text itself.
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 the tool's purpose: 'Retrieve a resource by specifying both the resource ID and the format' and 'allows for precise downloading of resources in the desired format.' It specifies the verb (retrieve/download) and resource (resource by ID and format). However, it doesn't explicitly differentiate from sibling tools like 'download_resource_by_id' or 'get_resource_detail_by_id', which appear to serve similar purposes with different approaches.
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. It doesn't mention sibling tools like 'download_resource_by_id' or 'get_resource_detail_by_id', nor does it specify prerequisites, constraints, or typical use cases. The only implied usage is for downloading resources with specific formats, but no comparative context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_iconsC
Get a list of icons based on the provided parameters and ordering criteria.
Query Parameters:
term: Search term. If only term comes, it is searched for term, if only slug comes, it is searched for slug and if both come, it is searched for slug
slug: Search by slug
page: Page number. It must be greater than 0.
per_page: Results per page. It must be greater than 0.
family-id: Icon family id.
order: Define order of results.
Note: If the term or slug parameter is used, the order will be the similarity of the search.
thumbnail_size: Size of the thumbnail. If the size is not specified, the API will return 128 as a default size.
filters: Filter parameters for icons
Responses:
200 (Success): OK Response
Content-Type:
application/jsonResponse Properties:
Example:
{
"data": [
{
"free_svg": true,
"created": "2023-03-07T23:05:26Z",
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "a woman reads a book in a tablet sits in the luxurious back of the library",
"style": {
"name": "Meticulous Yellow shadow",
"id": 50
},
"id": 52912,
"family": {
"total": 1200,
"name": "Outline",
"id": 1
},
"thumbnails": [
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
},
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
}
],
"slug": "a-woman-reads-a-book-in-a-tablet-sits-in-the-luxurious-back-of-the-library",
"tags": [
{
"name": "Dog",
"slug": "dog"
},
{
"name": "Dog",
"slug": "dog"
}
]
},
{
"free_svg": true,
"created": "2023-03-07T23:05:26Z",
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"name": "a woman reads a book in a tablet sits in the luxurious back of the library",
"style": {
"name": "Meticulous Yellow shadow",
"id": 50
},
"id": 52912,
"family": {
"total": 1200,
"name": "Outline",
"id": 1
},
"thumbnails": [
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
},
{
"width": 512,
"url": "https://v4.cdnpk.net/videvo_files/video/free/video0485/thumbnails/_import_61a866e2519c71.61070863_large.png",
"height": 512
}
],
"slug": "a-woman-reads-a-book-in-a-tablet-sits-in-the-luxurious-back-of-the-library",
"tags": [
{
"name": "Dog",
"slug": "dog"
},
{
"name": "Dog",
"slug": "dog"
}
]
}
],
"meta": {
"pagination": {
"per_page": 1,
"total": 1,
"last_page": 1,
"current_page": 1
}
}
}400: Bad Request - The server could not understand the request due to invalid syntax.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}401: Unauthorized - The client must authenticate itself to get the requested response.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}404: Not Found - The server can not find the requested resource.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}500: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Internal Server Error"
}ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| Accept-Language | No | Specifies the search query language using the ISO 639-1 (2-letter language code) and the ISO 3166-1 (2-letter country code) for language variants. The API will use "en-US" as a default language for processing if a code is not provided, or does not exist. | |
| term | No | Search term. If only term comes, it is searched for term, if only slug comes, it is searched for slug and if both come, it is searched for slug | |
| slug | No | Search by slug | |
| page | No | Page number. It must be greater than 0. | |
| per_page | No | Results per page. It must be greater than 0. | |
| family-id | No | Icon family id. | |
| order | No | Define order of results. - Note: If the term or slug parameter is used, the order will be the similarity of the search. | relevance |
| thumbnail_size | No | Size of the thumbnail. If the size is not specified, the API will return 128 as a default size. | |
| filters | No | Filter parameters for icons |
TDQS
C2.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds some context: it describes pagination behavior (via 'page' and 'per_page'), default values (e.g., 'thumbnail_size' defaults to 128), and search logic (e.g., term/slug interactions). However, it lacks details on rate limits, authentication needs, or error handling beyond HTTP codes, leaving gaps for a tool with 9 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is overly verbose and poorly structured. It front-loads the purpose but then duplicates schema details and includes extensive, repetitive JSON examples for responses. The 'Query Parameters' and 'Responses' sections add bulk without significant new information, making it inefficient and hard to scan.
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 tool's complexity (9 parameters, nested objects) and lack of annotations or output schema, the description is moderately complete. It covers basic functionality, parameters, and response formats with examples, but it misses behavioral aspects like authentication requirements or rate limits. The inclusion of HTTP response details helps, but it's not fully compensatory for the missing structured data.
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 the schema already documents all parameters thoroughly. The description repeats parameter information in the 'Query Parameters' section, adding minimal value beyond the schema. It does clarify interactions (e.g., term/slug search logic) and defaults, but this is largely redundant with the schema descriptions.
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 the tool's purpose: 'Get a list of icons based on the provided parameters and ordering criteria.' It specifies the verb ('Get') and resource ('icons'), and distinguishes it from siblings like 'download_icon_by_id' or 'get_icon_detail_by_id' by focusing on search/list functionality. However, it doesn't explicitly differentiate from 'search_resources' (a sibling tool), which might cause ambiguity.
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. It doesn't mention sibling tools like 'search_resources' (which might overlap) or 'get_icon_detail_by_id' (for single icons), nor does it specify prerequisites or exclusions. Usage is implied through the description of parameters but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_resourcesC
Retrieve a list of resources based on various filter criteria such as orientation, content type, license, and more.
Query Parameters:
page: Page number. It must be greater than 0 and less than or equal to 100.
limit: Limit results per page. It must be greater than 0.
order: Specifies the order in which search results are returned. The available options allow you to prioritize results based on different criteria:
relevance: Prioritizes results that are most relevant to the search query.recent: Sorts results by the most recent updates.term: Search term. If only term comes, it is searched for term, if only slug comes, it is searched for slug and if both come, it is searched for slug
filters: Advanced filtering options for resources
Responses:
200 (Success): Ok Response
Content-Type:
application/jsonResponse Properties:
data: A list of resources.
Example:
{
"data": [
{
"image": {
"orientation": "horizontal",
"source": {
"size": "740x640",
"key": "large",
"url": "https://img.freepik.com/free-photo/tshirt_53876-104920.jpg"
},
"type": "vector"
},
"licenses": [
{
"type": "freemium",
"url": "https://www.freepik.com/profile/license/pdf/4350594"
},
{
"type": "freemium",
"url": "https://www.freepik.com/profile/license/pdf/4350594"
}
],
"filename": "filename",
"related": {
"keywords": {
"name": "Merry Christmas",
"slug": "merry-christmas"
},
"serie": {
"image": {
"orientation": "horizontal",
"source": {
"size": "740x640",
"key": "large",
"url": "https://img.freepik.com/free-photo/tshirt_53876-104920.jpg"
},
"type": "vector"
},
"licenses": [
{
"type": "freemium",
"url": "https://www.freepik.com/profile/license/pdf/4350594"
},
{
"type": "freemium",
"url": "https://www.freepik.com/profile/license/pdf/4350594"
}
],
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"id": 15667327,
"title": "White t-shirt with copy space on gray background",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
},
"others": {
"image": {
"orientation": "horizontal",
"source": {
"size": "740x640",
"key": "large",
"url": "https://img.freepik.com/free-photo/tshirt_53876-104920.jpg"
},
"type": "vector"
},
"licenses": [
{
"type": "freemium",
"url": "https://www.freepik.com/profile/license/pdf/4350594"
},
{
"type": "freemium",
"url": "https://www.freepik.com/profile/license/pdf/4350594"
}
],
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"id": 15667327,
"title": "White t-shirt with copy space on gray background",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
}
},
"stats": {
"downloads": 0,
"likes": 0
},
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"meta": {
"is_new": true,
"available_formats": {
"psd": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"jpg": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"zip": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"fonts": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"svg": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"ai": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"png": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"eps": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"resources": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"3d-render": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"atn": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
}
},
"published_at": "2020-12-01T23:50:50Z"
},
"id": 15667327,
"title": "White t-shirt with copy space on gray background",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm",
"products": [
{
"type": "essential",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
},
{
"type": "essential",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
}
]
},
{
"image": {
"orientation": "horizontal",
"source": {
"size": "740x640",
"key": "large",
"url": "https://img.freepik.com/free-photo/tshirt_53876-104920.jpg"
},
"type": "vector"
},
"licenses": [
{
"type": "freemium",
"url": "https://www.freepik.com/profile/license/pdf/4350594"
},
{
"type": "freemium",
"url": "https://www.freepik.com/profile/license/pdf/4350594"
}
],
"filename": "filename",
"related": {
"keywords": {
"name": "Merry Christmas",
"slug": "merry-christmas"
},
"serie": {
"image": {
"orientation": "horizontal",
"source": {
"size": "740x640",
"key": "large",
"url": "https://img.freepik.com/free-photo/tshirt_53876-104920.jpg"
},
"type": "vector"
},
"licenses": [
{
"type": "freemium",
"url": "https://www.freepik.com/profile/license/pdf/4350594"
},
{
"type": "freemium",
"url": "https://www.freepik.com/profile/license/pdf/4350594"
}
],
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"id": 15667327,
"title": "White t-shirt with copy space on gray background",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
},
"others": {
"image": {
"orientation": "horizontal",
"source": {
"size": "740x640",
"key": "large",
"url": "https://img.freepik.com/free-photo/tshirt_53876-104920.jpg"
},
"type": "vector"
},
"licenses": [
{
"type": "freemium",
"url": "https://www.freepik.com/profile/license/pdf/4350594"
},
{
"type": "freemium",
"url": "https://www.freepik.com/profile/license/pdf/4350594"
}
],
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"id": 15667327,
"title": "White t-shirt with copy space on gray background",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
}
},
"stats": {
"downloads": 0,
"likes": 0
},
"author": {
"assets": 0,
"name": "John Doe",
"id": 2147483647,
"avatar": "https://avatar.cdnpk.net/61668527-220726032514.jpg",
"slug": "merry-christmas"
},
"meta": {
"is_new": true,
"available_formats": {
"psd": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"jpg": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"zip": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"fonts": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"svg": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"ai": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"png": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"eps": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"resources": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"3d-render": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
},
"atn": {
"total": 1,
"items": [
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
},
{
"size": 100,
"colorspace": "RGB",
"name": "image.jpg",
"id": 1
}
]
}
},
"published_at": "2020-12-01T23:50:50Z"
},
"id": 15667327,
"title": "White t-shirt with copy space on gray background",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm",
"products": [
{
"type": "essential",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
},
{
"type": "essential",
"url": "https://www.freepik.com/free-photo/white-t-shirts-with-copy-space-gray-background_15667327.htm"
}
]
}
],
"meta": {
"per_page": 1,
"total": 1,
"last_page": 1,
"current_page": 1,
"clean_search": true
}
}400: Bad Request - The server could not understand the request due to invalid syntax.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}401: Unauthorized - The client must authenticate itself to get the requested response.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}403: Forbidden - The client does not have permission to access the requested resource.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}404: Not Found - The server can not find the requested resource.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}503: Service Unavailable
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Service Unavailable. Please try again later."
}ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| Accept-Language | No | Specifies the search query language using the ISO 639-1 (2-letter language code) and the ISO 3166-1 (2-letter country code) for language variants. The API will use "en-US" as a default language for processing if a code is not provided, or does not exist. | |
| page | No | Page number. It must be greater than 0 and less than or equal to 100. | |
| limit | No | Limit results per page. It must be greater than 0. | |
| order | No | Specifies the order in which search results are returned. The available options allow you to prioritize results based on different criteria: - `relevance`: Prioritizes results that are most relevant to the search query. - `recent`: Sorts results by the most recent updates. | relevance |
| term | No | Search term. If only term comes, it is searched for term, if only slug comes, it is searched for slug and if both come, it is searched for slug | |
| filters | No | Advanced filtering options for resources |
TDQS
C2.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does mention pagination behavior (page/limit parameters) and includes extensive HTTP response documentation with status codes and examples. However, it doesn't cover important aspects like rate limits, authentication requirements, or whether this is a read-only operation (though 'retrieve' implies read-only).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is excessively long and poorly structured. It includes massive JSON response examples (over 500 lines) that belong in an output schema, not a tool description. The core purpose statement is buried under parameter details and response documentation. While the initial sentence is concise, the overall structure is bloated with redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex search tool with 6 parameters, nested objects, and no output schema, the description is incomplete. While it documents HTTP responses extensively, it lacks crucial context about authentication, rate limits, error handling beyond HTTP codes, and how to interpret the complex response structure. The massive example doesn't compensate for missing behavioral 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 schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description repeats some parameter information (page, limit, order, term, filters) but doesn't add significant semantic value beyond what's in the schema. The baseline of 3 is appropriate when the schema does the heavy lifting.
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 the tool's purpose: 'Retrieve a list of resources based on various filter criteria.' It specifies the verb ('retrieve'), resource ('resources'), and scope ('based on various filter criteria'). However, it doesn't explicitly differentiate from sibling tools like 'search_icons' or 'get_resource_detail_by_id', which would be needed for a perfect score.
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. It doesn't mention sibling tools like 'search_icons' for icon-specific searches or 'get_resource_detail_by_id' for single resource details. There's no context about prerequisites, authentication requirements, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
text_to_image_mystic_syncC
Convert descriptive text input into images using AI. This endpoint accepts a variety of parameters to customize the generated images.
Responses:
200 (Success): OK - The request has succeeded and the Mystic process has started.
Content-Type:
application/jsonResponse Properties:
Example:
{
"data": {
"generated": [
"https://openapi-generator.tech",
"https://openapi-generator.tech"
],
"task_id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
"status": "CREATED"
}
}400: Bad Request - The server could not understand the request due to invalid syntax.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}401: Unauthorized - The client must authenticate itself to get the requested response.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "message"
}500: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Internal Server Error"
}503: Service Unavailable
Content-Type:
application/jsonResponse Properties:
Example:
{
"message": "Service Unavailable. Please try again later."
}ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | ### AI Model Prompt Description The prompt is a short text that describes the image you want to generate. It can range from simple descriptions, like `"a cat"`, to detailed scenarios, such as `"a cat with wings, playing the guitar, and wearing a hat"`. If no prompt is provided, the AI will generate a random image. #### Adding Characters to the Prompt You can introduce characters into the prompt using the following syntax: - `@character_name`: Represents the character you want to include. Example: `My friend @john is a great artist.` #### Modifying Character Strength To adjust the influence or "strength" of a character in the image, use the following syntax: - `@character_name::strength`: Specify the character's strength by appending `::strength` to their name, where `strength` is a numerical value. Example: `My friend @john::200 is a great artist.` Higher strength values will make the character more prominent in the generated image. | |
| webhook_url | No | Optional callback URL that will receive asynchronous notifications whenever the task changes status. The payload sent to this URL is the same as the corresponding GET endpoint response, but without the data field. | |
| structure_reference | No | ### Structure Reference Base64 image to use as structure reference. Using images as structure references allows you to influence the shape of your final image. This feature enables various creative applications such as coloring sketches, transforming cartoons into realistic images, texturing basic 3D models, or converting real images into cartoons. The outcome is entirely controlled by your prompt, offering limitless creative possibilities. | |
| structure_strength | No | Note: This parameter only takes effect when a `"structure_reference"` image is provided. Allows to maintain the structure of the original image. | |
| style_reference | No | ### Style Reference Base64 image to use as style reference. Using images as style references allows you to influence the aesthetic of your creation. This is possibly the most powerful tool of Mystic, as it truly lets you create incredibly unique images. | |
| adherence | No | Note: This parameter only takes effect when a `"style_reference"` image is provided. Increasing this value will make your generation more faithful to the prompt, but it may transfer the style a bit less accurately. Higher values can help fix small artifacts, anatomical errors and text readability. Lower values will give you more creative images and closer to the style reference. | |
| hdr | No | Note: This parameter only takes effect when a `"style_reference"` image is provided. Increasing this value can give you a more detailed image, at the cost of a more 'AI look' and slightly worse style transfer. Lower values have a more natural and artistic look but may increase artifacts. | |
| resolution | No | Resolution of the image | 2k |
| aspect_ratio | No | Image size with the aspect ratio. The aspect ratio is the proportional relationship between an image's width and height, expressed as *_width_height (e.g., square_1_1, widescreen_16_9). It is calculated by dividing the width by the height.\ If not present, the default is `square_1_1`. Note: For the `fluid` model, only this values are valid: * square_1_1 * social_story_9_16 * widescreen_16_9 * traditional_3_4 * classic_4_3 | square_1_1 |
| model | No | * `zen` - for smoother, basic, and cleaner results. Fewer objects in the scene and less intricate details. The softer looking one. * `flexible` - good prompt adherence. However, it has results that are a bit more HDR and saturated than Realism or Fluid. It's especially good with illustrations, fantastical prompts, and for diving into the latent space in search of very specific visual styles. * `fluid` - the model that adheres best to prompts with great average quality for all kind of images. It can generate really creative images! It will always follow your input no matter what. However, since it is using Google's Imagen 3, it is a bit over-moderated, and some simple prompts containing words like "war" may be flagged and not generated (sorry about that! But there's nothing we can do!). * `realism` - with a more realistic color palette. It tries to give an extra boost of reality to your images, a kind of "less AI look". Works especially well with photographs but also magically works with illustrations too. IMPORTANT: you should use Zen, Flexible or Fluid if you are trying to generate something that is really fantastic or a known character, Realism may not follow your prompt well. * `super_real` - if reality is your priority, this is your model. Nearly as versatile as Flexible, it excels in realism outperforming Editorial Portraits in medium shots, though not as strong for close-ups. * `editorial_portraits` - the most amazing state-of-the-art generator for editorial portraits. You have never seen a level of realism like this before. Perfect for hyperrealistic close-up or medium shots. Unfortunately, in wide or distant shots, it generates anatomical problems and artifacts... but for close-ups, it is simply the best on the market. Tip: use the longest and most explanatory prompts possible, they really suit it well! | realism |
| creative_detailing | No | Higher values can achieve greater detail per pixel at higher resolutions at the cost of giving a somewhat more "HDR" or artificial look. Very high values can generate quite crazy things like eyes where they shouldn't appear, etc. Valid values range `[0, 100]`, default `33` | |
| engine | No | Select the engine for the AI model. Available options: * `automatic` - default choice * `Illusio` - for smoother illustrations, landscapes, and nature. The softer looking one. * `Sharpy` - better for realistic images like photographs and for a more grainy look. It provides the sharpest and most detailed images. If you use it for illustrations it will give them more texture and a less softer look. * `Sparkle` - also good for realistic images. It's a middle ground between Illusio and Sharpy. | automatic |
| fixed_generation | No | When this option is enabled, using the same settings will consistently produce the same image. Fixed generations are ideal for fine-tuning, as it allows for incremental changes to parameters (such as the prompt) to see subtle variations in the output. When disabled, expect each generation to introduce a degree of randomness, leading to more diverse outcomes. | |
| filter_nsfw | No | Controls **NSFW** (Not Safe For Work) content filtering during generation. This parameter is always set to `true` by default and NSFW filtering **cannot be disabled** for standard API usage. Only authorized clients with special permissions can disable this filter. **Important:** If your use case requires disabling NSFW filtering, please contact our support team to discuss your requirements and potential authorization. | |
| styling | No |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool is an 'endpoint' and includes HTTP response codes (200, 400, etc.), implying it's a web API call, but lacks critical behavioral details such as authentication requirements, rate limits, asynchronous processing (implied by 'task_id' but not explained), or potential side effects like resource consumption.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is poorly structured and not front-loaded. It starts with a concise purpose statement but devotes most of its length to verbose HTTP response examples and formatting, which are redundant for an AI agent and clutter the core information. This wastes space and reduces clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (15 parameters, no annotations, no output schema), the description is incomplete. It lacks essential context such as authentication needs, rate limits, asynchronous behavior explanation, error handling beyond HTTP codes, and guidance on parameter combinations. The heavy reliance on the schema is insufficient for a tool of this sophistication.
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 high at 93%, so the baseline is 3. The description adds minimal value beyond the schema, stating only 'This endpoint accepts a variety of parameters to customize the generated images,' which is generic and doesn't elaborate on parameter interactions or usage scenarios. It doesn't compensate for the 7% coverage gap.
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 purpose: 'Convert descriptive text input into images using AI.' It specifies the verb ('convert'), resource ('descriptive text input'), and output ('images'), and distinguishes it from sibling tools like detect_ai_image or search_icons by focusing on generation rather than detection, download, or search.
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. It mentions 'This endpoint accepts a variety of parameters to customize the generated images,' but offers no explicit context, prerequisites, or comparisons to sibling tools, leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
1 tool update
v1.0.0- Changed
text_to_image_mystic_sync2 fields changed- changed
Input schema / properties / model / descriptionPrevious value: -"* `zen` - for smoother, basic, and cleaner results. Fewer objects in the scene and less intricate details. The softer looking one.\n* `fluid` - the model that adheres best to prompts with great average quality for all kind of images. It can generate really creative images! It will always follow your input no matter what. However, since it is using Google's Imagen 3, it is a bit over-moderated, and some simple prompts containing words like \"war\" may be flagged and not generated (sorry about that! But there's nothing we can do!).\n* `realism` - with a more realistic color palette. It tries to give an extra boost of reality to your images, a kind of \"less AI look\". Works especially well with photographs but also magically works with illustrations too.\n\n`IMPORTANT`: You should use Zen or Fluid if you are trying to generate something that is really fantastic or a known character, Realism may not follow your prompt well.\n"New value: +"* `zen` - for smoother, basic, and cleaner results. Fewer objects in the scene and less intricate details. The softer looking one.\n\n* `flexible` - good prompt adherence. However, it has results that are a bit more HDR and saturated than Realism or Fluid. It's especially good with illustrations, fantastical prompts, and for diving into the latent space in search of very specific visual styles.\n\n* `fluid` - the model that adheres best to prompts with great average quality for all kind of images. It can generate really creative images! It will always follow your input no matter what. However, since it is using Google's Imagen 3, it is a bit over-moderated, and some simple prompts containing words like \"war\" may be flagged and not generated (sorry about that! But there's nothing we can do!).\n\n* `realism` - with a more realistic color palette. It tries to give an extra boost of reality to your images, a kind of \"less AI look\". Works especially well with photographs but also magically works with illustrations too. IMPORTANT: you should use Zen, Flexible or Fluid if you are trying to generate something that is really fantastic or a known character, Realism may not follow your prompt well.\n\n* `super_real` - if reality is your priority, this is your model. Nearly as versatile as Flexible, it excels in realism outperforming Editorial Portraits in medium shots, though not as strong for close-ups.\n\n* `editorial_portraits` - the most amazing state-of-the-art generator for editorial portraits. You have never seen a level of realism like this before. Perfect for hyperrealistic close-up or medium shots. Unfortunately, in wide or distant shots, it generates anatomical problems and artifacts... but for close-ups, it is simply the best on the market. Tip: use the longest and most explanatory prompts possible, they really suit it well!\n" - changed
Input schema / properties / model / enumPrevious value: -[ - "realism", - "fluid", - "zen" -]New value: +[ + "realism", + "fluid", + "zen", + "flexible", + "super_real", + "editorial_portraits" +]
9 tool updates
- First observed
detect_ai_image - First observed
download_icon_by_id - First observed
download_resource_by_id - First observed
get_icon_detail_by_id - First observed
get_resource_detail_by_id - First observed
get_resource_download_formats - First observed
search_icons - First observed
search_resources - First observed
text_to_image_mystic_sync
TDQS
B3.2/5.0
Disambiguation4/5
Most tools have distinct purposes with clear boundaries, such as detect_ai_image for AI detection and text_to_image_mystic_sync for AI image generation. However, there is some overlap between download_resource_by_id and get_resource_download_formats, as both handle downloading resources by ID with format specifications, which could cause confusion. The descriptions help differentiate them, but the similarity in function is notable.
Naming Consistency5/5
All tool names follow a consistent snake_case pattern with a verb_noun structure, such as detect_ai_image, download_icon_by_id, and search_resources. This uniformity makes the tool set predictable and easy to understand, with no deviations in naming conventions across the nine tools.
Tool Count4/5
With 9 tools, the count is well within the typical 3-15 range for a well-scoped server, covering icon and resource management, AI detection, and image generation. It feels slightly heavy due to some redundancy in download functions, but overall, each tool serves a purpose in the Freepik domain, making it reasonable for the toolkit's scope.
Completeness4/5
The tool set provides strong coverage for searching, retrieving details, and downloading icons and resources, along with AI-related functions like detection and generation. Minor gaps exist, such as the lack of update or delete operations for resources, which are less critical in this context, and no tool for managing user accounts or licenses. However, core workflows for content discovery and access are well-supported.
Maintenance
ActivitySlowing
ResponsivenessSyncing
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
The Figma MCP server brings Figma design context directly into your AI workflow.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
- CanvaOAuthcom.canva.mcp
The Canva MCP server connects AI assistants (like Claude, ChatGPT, and Cursor) to Canva's API, enabling them to create and manage designs directly within chat conversations. Key capabilities include generating new designs from prompts, autofilling templates, searching and resizing existing designs, importing files from URLs, exporting designs as PDFs or images, and managing folders and comments without switching between tools.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to search, download, and generate visual content using Freepik APIs, including icon search, image generation, and resource management.-
- FlicenseNot gradedqualityDmaintenanceMCP server for searching, downloading Freepik stock resources and generating images using Mystic AI.-
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to search for royalty-free images from Pexels and Unsplash using natural language, returning structured results with metadata.559MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/freepik-company/freepik-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server