Manage AltText.ai account, generate alt text for images, and organize an image library.
Account management: check credits/usage and update account settings (name, webhook, notification email).
Alt text generation: generate alt text from a public image URL or a local file, with options for languages, keywords, custom prompts, character limits, and overwriting. Translate existing images into new languages.
Image library management: list, search, get details, update (alt text, tags, metadata), and delete images.
Bulk operations: queue alt text generation from a CSV file or scrape a web page to find images missing alt text and queue generation asynchronously.
Click on "Deploy 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., "@AltText.ai MCP Server Generate alt text for https://example.com/photo.jpg"
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.
An MCP server that lets AI assistants generate alt text, manage image libraries, and queue alt text generation for web page images using the AltText.ai API.
Works with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible client.
This server runs npx -y @alttext_ai/alttext-mcp, which downloads and executes code with your API key in its environment. That's worth a moment of verification before you install — by you or by an AI agent doing the setup. Everything below should match:
Signal | Value |
npm package | |
Source repository | |
Publisher | AltText.ai |
Provenance | Published from this repo's CI with npm provenance — npm shows a verified build badge linking the package to this exact commit |
The npm scope is @alttext_ai (with an underscore), while the GitHub org is alttextai (no underscore). This is intentional, not a typosquat: the @alttextai npm scope was already taken, so we publish under @alttext_ai. The two names refer to the same official AltText.ai package.
To cryptographically verify the published package was built by this repo's CI — not just trust the metadata — run:
npm audit signaturesfrom a project where the package is installed. This validates the registry signature and the npm provenance attestation, which links the tarball to a specific commit and GitHub Actions build. A counterfeit package can forge repository.url and other metadata, but it cannot forge the provenance attestation — so this is the check that actually matters.
(For a quick, weaker cross-reference of the claimed source you can run npm view @alttext_ai/alttext-mcp repository.url, but note that field is publisher-controlled metadata and proves nothing on its own.)
The setup snippet uses npx -y @alttext_ai/alttext-mcp, which always resolves to the latest published version and re-runs it on every launch. That keeps you current, but it also means a future release runs automatically without review. If you want a reproducible, audited install, pin a specific version:
"args": ["-y", "@alttext_ai/alttext-mcp@1.0.5"]Run npm audit signatures against the pinned version, and bump it deliberately when you're ready to take a new release.
Related MCP server: aria51 MCP Server
Requirements: Node.js 22+ and an AltText.ai API key
Add the server to your MCP client configuration:
{
"mcpServers": {
"alttext-ai": {
"command": "npx",
"args": ["-y", "@alttext_ai/alttext-mcp"],
"env": {
"ALTTEXT_API_KEY": "your-api-key"
}
}
}
}Where to add this:
Client | Config file |
Claude Desktop |
|
Claude Code |
|
Cursor | MCP settings in the Cursor preferences |
Windsurf | MCP settings in the Windsurf preferences |
Tool | Description |
| Check your credit balance, usage, and account settings. |
| Update account name, webhook URL, or notification email. |
Tool | Description |
| Generate alt text for an image URL. Supports multilingual output, custom prompts, keywords, and character limits. Uses account credits. |
| Generate alt text from a local image file. Automatically base64-encodes and uploads. Uses account credits. |
| Add alt text in a new language for an existing image (by asset_id). Uses account credits. |
Tool | Description |
| List images in your library with pagination. |
| Search your image library by alt text content. |
| Get details for a specific image by asset ID. |
| Update alt text, tags, or metadata for an image. |
| Delete an image from your library. |
Tool | Description |
| Bulk generate alt text from a CSV file with image URLs and optional metadata. |
| Scan a web page, find images missing alt text, and queue generation. Results are async -- use |
This package uses stdio and runs on the machine launching the MCP client. Image and CSV paths refer to that machine; selected file contents are uploaded to AltText.ai.
Generation and translation use your account credits. Additional languages and image conversion can increase the total. Check get_account before paid work. Generation can overwrite existing alt text when requested; updates replace supplied fields and deletion removes the image from the library.
CSV imports and page scraping queue background processing. An accepted request does not mean generation has finished; inspect the image library and any configured completion notifications. Tool annotations describe effects for clients; they do not enforce confirmation.
Once configured, just ask your AI assistant:
"How many credits do I have left?"
"Update my webhook URL to https://example.com/webhook"
"Generate alt text for https://example.com/photo.jpg"
"Generate alt text for this image" (with local file)
"Generate alt text in French and Spanish for this image"
"Translate image abc123 to German"
"Search my images for 'product photo'"
"List my images"
"Get details for image abc123"
"Update the alt text for asset abc123"
"Delete image xyz789"
"Generate alt text for images missing it on https://example.com"
"Process this CSV file of image URLs" (bulk_create)
Variable | Required | Description |
| Yes | Your AltText.ai API key |
| No | Override the API base URL (default: |
npm install
npm run build
npm test
npm run lintTests use mocked fetch calls -- no API key or network access needed.
Hosted deployments must rate-limit POST /register at a trusted edge using the verified client address. The Node service deliberately ignores forwarded client-address headers because accepting them without an authenticated proxy boundary would let callers spoof the rate-limit identity.
The production container and required settings are documented in docs/deployment.md.
MIT
server.json describes the stdio npm package. Its name matches mcpName in package.json; both versions must match the release being submitted. Publish and verify that exact npm version before running mcp-publisher publish. Registry acceptance and directory approval are separate from an npm release.
Upload a local CSV file from the MCP server machine and queue asynchronous alt-text generation using account credits. The response does not confirm generation completion. CSV should have columns: url (required), asset_id, lang, keywords, tags, metadata (optional).
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email for completion notification | ||
| csv_file | Yes | Path to CSV file with image URLs and optional metadata |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral context beyond annotations: the response does not confirm generation completion, the operation is asynchronous, and it consumes account credits. Also clarifies the CSV file must exist on the MCP server machine. Consistent with destructiveHint=true and readOnlyHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the first states the core operation, the second warns about the async response behavior, and the third specifies the CSV format. No fluff, front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a bulk async tool with a 2-param schema and annotations covering safety. The only gap is that no output schema exists and the description does not indicate what the response actually contains (e.g., a request ID) beyond stating it does not confirm completion. Minor, given the async nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds essential semantics not present in the schema: the exact CSV column structure (url required; asset_id, lang, keywords, tags, metadata optional). This goes beyond the schema's generic 'Path to CSV file with image URLs and optional metadata' and is critical for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action (upload local CSV, queue async alt-text generation) with a clear resource (CSV file) and scope (bulk, uses account credits). It distinguishes itself from siblings like generate_alt_text and generate_alt_text_from_file by emphasizing the bulk, asynchronous, local-file nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use the tool: when you have a local CSV on the MCP server machine and want asynchronous bulk generation. However, it does not explicitly name alternatives or state exclusions, leaving the agent to infer the distinction from the surrounding text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an image from your AltText.ai library
| Name | Required | Description | Default |
|---|---|---|---|
| asset_id | Yes | The asset ID of the image to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this mutates state. The description adds the library scope and confirms deletion, but does not go beyond annotations to disclose side effects or irreversibility. Since annotations carry the safety profile, a mid score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence that leads with the verb and object and contains no filler. It is appropriately minimal for a simple delete operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool with rich annotations (destructive, idempotent) and a fully documented schema, the description is sufficient for an agent to invoke the tool correctly. No output schema exists, but the description need not explain return values given the simplicity of the action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes asset_id as 'The asset ID of the image to delete' (100% coverage), so the description need not restate it. The description adds no parameter-level meaning beyond the schema, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('delete') and a specific resource ('an image from your AltText.ai library'), making the operation unambiguous. It clearly distinguishes this from sibling operations like update_image or list_images by naming the exact action and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended use obvious: call this when an image should be removed from the AltText.ai library. It does not explicitly name alternatives or exclusions, but for a single-purpose destructive action against siblings like update_image, the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate AI-powered alt text for an image URL. Returns the result synchronously (may take a few seconds). Uses account credits; additional languages and image conversion can increase the total. Can overwrite existing alt text when requested.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public URL of the image | |
| lang | No | Comma-separated language codes (e.g. 'en', 'en,fr,es') | |
| tags | No | Tags for organization | |
| asset_id | No | Custom asset ID (default: auto-generated hash) | |
| keywords | No | Keywords to incorporate | |
| metadata | No | Custom metadata (string key-value pairs) | |
| max_chars | No | Maximum character length for the alt text | |
| overwrite | No | Overwrite existing alt text if image was previously processed | |
| gpt_prompt | No | Custom prompt template. Use {{AltText}} as a placeholder for the generated alt text. | |
| negative_keywords | No | Keywords to avoid |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses non-obvious behavior beyond the annotations: synchronous result with a few seconds latency, account-credit usage, cost increase for languages/conversion, and conditional overwrite of existing alt text. This complements the destructiveHint/readOnlyHint annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no filler; the primary action is front-loaded and each subsequent sentence adds a distinct piece of behavioral or billing context. Very efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter, no-output-schema tool, the description covers the important high-level behaviors (latency, cost, overwrite), but it does not describe the shape or content of the returned result beyond 'the result.' It also introduces 'image conversion' without tying it to a listed parameter, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the descriptions of all 10 parameters already carry most meaning. The tool description adds only a couple of value-added links (language selection affects credits; overwrite only happens when requested), which is useful but not a major contribution beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Generate AI-powered alt text for an image URL'), and the URL input distinguishes it from the sibling generate_alt_text_from_file. The purpose is unambiguous and not a restatement of the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context for deciding to call it—synchronous latency, credit consumption, and optional overwrite—but it never explicitly states when to choose this tool over generate_alt_text_from_file or mentions alternatives. The URL qualifier implies the intended input, so usage is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate alt text from a local image file. Reads a file on the MCP server machine and uploads it to AltText.ai. Uses account credits; additional languages and image conversion can increase the total. Can overwrite existing alt text when requested.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Comma-separated language codes (e.g. 'en', 'en,fr,es') | |
| tags | No | Tags for organization | |
| asset_id | No | Custom asset ID (default: auto-generated hash) | |
| keywords | No | Keywords to incorporate | |
| metadata | No | Custom metadata (string key-value pairs) | |
| file_path | Yes | Absolute path to a local image file | |
| max_chars | No | Maximum character length for the alt text | |
| overwrite | No | Overwrite existing alt text if image was previously processed | |
| gpt_prompt | No | Custom prompt template. Use {{AltText}} as a placeholder for the generated alt text. | |
| negative_keywords | No | Keywords to avoid |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructiveness and non-read-only, and the description adds genuinely useful context: local file system reads, the external AltText.ai upload, account credit consumption, and cost increases from extra languages and image conversion. The overwrite caveat ('when requested') aligns coherently with destructiveHint=true, with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each carrying distinct operational information, with the core purpose front-loaded in the first sentence. There is no filler, no repetition of schema content, and each clause — local file access, upload target, credit cost, overwrite behavior — earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with a nested object and external side effects, the description covers the key operational facts: server-side file access, upload destination, cost implications, and overwrite behavior. It does not describe the return value, which is a moderate gap given no output schema exists, but the fully documented parameters keep it functional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline of 3 applies — all 10 parameters are already documented in the schema. The description adds a small amount of meaning by tying the lang parameter to increased credit usage, but nothing else beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'Generate alt text from a local image file,' then clarifies the mechanism: 'Reads a file on the MCP server machine and uploads it to AltText.ai.' This clearly distinguishes it from the sibling generate_alt_text, which is the main confusion risk, by grounding it in local file input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its niche — local files on the server machine — but never explicitly states when to prefer it over the sibling generate_alt_text or any other alternative. No when-not-to-use guidance or exclusion criteria is given, leaving the agent to infer routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get your AltText.ai account info including credit balance, usage, and settings
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, non-destructive nature, so the description does not need to repeat that. It adds useful context by saying 'your' account and naming the returned categories, but it does not discuss auth expectations, rate limits, or output format. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, compact sentence that front-loads the resource and then lists the included information. Every word contributes meaning, with no repetition, filler, or ambiguity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only account tool, this description is complete. Annotations define the operational safety profile, and the description enumerates the relevant returned information since no output schema exists. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so parameter documentation is a non-issue. The description's 'your account' wording usefully signals that the account is determined by the authenticated caller rather than an explicit parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get') and resource ('your AltText.ai account info'), then adds what is included: credit balance, usage, and settings. This is unambiguous and naturally separates it from siblings like update_account, which implies modification, and the image-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit when-to-use guidance, exclusions, or alternatives. It does not mention update_account or explain when retrieving account info is preferable to modifying it; usage context is only implied by the tool's name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details for a specific image by its asset ID
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Filter alt texts by language code | |
| asset_id | Yes | The asset ID of the image |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds little beyond 'get details,' with no mention of response format, language filtering behavior, or potential edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. It communicates the operation, the resource, and the required identifier efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with strong annotations and complete schema descriptions, the description is sufficient for correct invocation. It could be more explicit about what 'details' includes, especially given the absence of an output schema, but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well documented. The description repeats the asset_id concept but does not add meaning beyond the schema for either parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get details') with a clear resource ('specific image') and the key identifier ('asset ID'). It is easily distinguishable from sibling tools like list_images, search_images, update_image, and delete_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by its asset ID' clearly indicates the tool is for retrieving a single known image, not for listing or searching. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List images in your AltText.ai library with pagination
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Filter images by exact URL match | |
| lang | No | Filter alt texts by language code | |
| page | No | Page number (default: 1) | |
| sort | No | Sort column (default: id) | |
| limit | No | Items per page (default: 20, max: 100) | |
| direction | No | Sort direction (default: DESC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the description need not repeat safety. It does add 'with pagination,' but this is already implied by the page and limit schema fields. No additional behavioral context (e.g., return format, ordering defaults) is disclosed beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the core purpose without any filler. It is appropriately sized for a simple listing operation, and every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward listing tool with comprehensive annotations and full schema coverage, the description is mostly sufficient. The main gap is the lack of disambiguation between list_images and search_images, and no explicit mention of the return format (though no output schema exists). Overall, the definition is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive entries for all six parameters (url, lang, page, sort, limit, direction). The description itself adds no parameter-level detail, but the schema already provides adequate meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists images in the AltText.ai library, providing a specific verb and resource. However, it does not differentiate from sibling tools like search_images, leaving some ambiguity about the exact scope (list all vs. list filtered).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as search_images, get_image, or filter by URL. There are no explicit use-case conditions or exclusions, leaving the agent to infer when a plain list is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find images on a web page and queue alt-text generation jobs. Uses account credits. Images are processed asynchronously; inspect the image library for results.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL of the web page to scrape | |
| html | No | Optional HTML override (if omitted, server fetches the page) | |
| lang | No | Comma-separated language codes (e.g. 'en', 'en,fr,es') | |
| keywords | No | Keywords to incorporate | |
| max_chars | No | Maximum character length for the alt text | |
| gpt_prompt | No | Custom prompt template. Use {{AltText}} as a placeholder for the generated alt text. | |
| include_existing | No | Include images that already have alt text | |
| negative_keywords | No | Keywords to avoid |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag that this is not read-only and is destructive, but the description adds crucial operational context: it consumes account credits, processes asynchronously, and requires inspecting the image library for results. This goes beyond the schema and annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, with the core purpose first, then cost, then async behavior. No filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with eight parameters and no output schema, the description gives the essential workflow: result location, async nature, and cost. It does not cover edge cases or detailed return structure, but the schema and annotations cover the rest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All eight parameters have schema descriptions, so the description carries little parameter burden. It adds no parameter-level details beyond the schema, but none are missing enough to lower the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete action and resource: 'Find images on a web page' and 'queue alt-text generation jobs'. This clearly separates it from direct-generation siblings such as generate_alt_text or generate_alt_text_from_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies the intended use case (web page as source, asynchronous job queue) and notes results appear in the image library. However, it never explicitly names alternatives or states when not to use this tool, so routing guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search images by alt text content
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Filter by language code | |
| limit | No | Max results to return (default: 20) | |
| query | Yes | Search query to match against alt text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the behavioral detail that matching is against alt text, which is useful context. However, it does not disclose any edge behaviors like case sensitivity, wildcard matching, or what happens when alt text is missing—minor given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that states the operation and its key constraint with zero filler. The most important qualifier ('by alt text content') is front-loaded, so an agent scanning the description immediately knows the tool's scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool, the description plus fully documented schema and safety annotations cover the essentials: what it searches, the filter parameters, and the safe read-only behavior. It does not describe return format, but no output schema exists and search tools are common enough that this is not a critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents query, lang, and limit. The description essentially restates the query field's purpose ('alt text content') without adding extra semantics such as default ordering or how lang filtering interacts with alt text. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('search') with a clear resource ('images') and a defining qualifier ('by alt text content'). This distinguishes it from siblings like list_images (which would list without searching) and get_image (which fetches a single image), so an agent can tell them apart without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when the agent needs to find images by alt text—but provides no explicit guidance about when not to use it or which sibling to prefer (e.g., list_images vs search_images). Usage is inferable but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add alt text in a new language for an existing image. Uses the asset_id to find the image and generates a translation. Uses account credits for each newly generated language.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | Yes | Target language code(s), comma-separated (e.g. 'de', 'fr,es') | |
| asset_id | Yes | The asset ID of the existing image to translate |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag readOnlyHint=false and idempotentHint=false. The description adds the meaningful side effect of consuming account credits per language, which is beyond what annotations capture. It also implies a generation process that may have latency. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler. The primary action is front-loaded, and the credit cost is stated concisely. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with full schema coverage and annotations indicating mutation and non-idempotency, the description covers the essential purpose, cost, and mechanism. It lacks mention of return format or latency, but those are not critical for correct invocation given the context signals.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are well-documented in the schema. The description reinforces the role of asset_id in locating the image but adds no new semantic detail about lang beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Add') and resource ('alt text in a new language for an existing image'), with the asset_id mechanism. It clearly differentiates from generate_alt_text by emphasizing translation of existing alt text, so an agent can infer the right tool without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context (uses asset_id, generates translation, consumes credits) but does not explicitly state when to use this versus generate_alt_text or when not to use it. No exclusions are given, so the agent must infer the boundary from the purpose statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update your AltText.ai account settings (name, webhook URL, notification email)
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Account name | |
| webhook_url | No | Webhook URL for processing notifications | |
| notification_email | No | Email address for notifications |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate that this is a mutating, destructive, idempotent operation. The description adds scoping by listing the three settings affected, but it does not clarify partial-update behavior, replacement semantics, or consequences beyond the annotation flags. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence immediately states the action, resource, and affected fields. There is no filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple optional-field account update, the description combined with schema and annotations is sufficient for an agent to understand why and how to invoke it. The only notable omission is explicit confirmation of partial-update semantics and the response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already well documented. The description merely repeats the field names and adds no format, constraint, or usage nuance beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Update' targets a specific resource, 'AltText.ai account settings', and enumerates the exact fields affected (name, webhook URL, notification email). This clearly distinguishes it from sibling tools like get_account and update_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly identifies the tool as the one for modifying account-level settings rather than images or generation tasks. It does not explicitly name alternatives or state when not to use it, but the context is plain and unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update alt text and/or metadata for an existing image
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language code for the alt text (default: 'en') | |
| tags | No | Replace tags | |
| alt_text | No | New alt text value | |
| asset_id | Yes | The asset ID of the image to update | |
| metadata | No | Replace metadata (string key-value pairs) | |
| overwrite | No | If false, skip language entries that already exist |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already carry destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety and mutation profile is established outside the description. The description itself adds no behavioral detail such as replacement semantics, overwrite behavior, or side effects, but it does not contradict the annotations either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loads the primary action, and conveys the core purpose quickly. It is appropriately sized for a straightforward update operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations and fully documented schema, an agent has enough structured information to call the tool correctly. However, the description itself is thin: it does not discuss return behavior, destructive replacement semantics, or relationships to sibling tools, so the surrounding context is only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains each parameter, including 'Replace tags' and 'Replace metadata'. The description adds no extra parameter meaning beyond naming alt text and metadata, and it omits tags entirely, so it provides no value beyond the structured schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('update') and resource ('existing image'), and names the main fields ('alt text and/or metadata'). However, the schema also supports updating tags and language/overwrite behavior, so the description undersells the full scope and does not fully distinguish it from sibling tools like generate_alt_text or translate_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for an existing image' implies the tool modifies previously created assets rather than creating new ones, providing some usage context. Still, it gives no explicit guidance about when to choose this tool over siblings such as generate_alt_text, translate_image, or delete_image, and no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.5bulk_create1 field changedInput schema / properties / email / patternPrevious value: -"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"New value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"update_account1 field changedInput schema / properties / notification_email / patternPrevious value: -"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"New value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"v1.0.4bulk_createdelete_imagegenerate_alt_textgenerate_alt_text_from_fileget_accountget_imagelist_imagesscrape_pagesearch_imagestranslate_imageupdate_accountupdate_imageScored across 12 tools
Each tool targets a distinct resource and action: account management, single-image generation by URL/file, translation, image library CRUD, and batch/scrape enqueueing. The potentially similar generation tools are clearly separated by input type and sync/async behavior.
All tool names use lowercase snake_case and generally follow a verb_noun pattern (get_account, list_images, delete_image). Longer names like generate_alt_text_from_file and bulk_create remain predictable and readable.
Twelve tools is well-scoped for an alt-text generation service covering account settings, image library operations, single generation, translation, and batch workflows. Every tool maps to a meaningful operation without redundancy.
The surface covers account management, CRUD for images, and multiple generation paths (URL, file, translation, CSV batch, web scraping). The main gap is the lack of an explicit async job status tool; bulk_create and scrape_page require inspecting the image library to confirm completion.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
One API for 100+ AI video, image, music and speech models.
Real SEO data for AI assistants: page audits, Keyword Planner volumes, Search Console history.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
