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., "@tolgee-mcp list all translation projects"
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 wraps the Tolgee localization platform API, enabling LLMs to manage translation projects, keys, translations, languages, and related workflows.
The only prerequisite is uv.
Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"tolgee": {
"command": "uvx",
"args": ["tolgee-mcp"],
"env": {
"TOLGEE_API_KEY": "your-api-key"
}
}
}
}Add to your opencode.json:
{
"mcp": {
"tolgee": {
"type": "local",
"command": ["uvx", "tolgee-mcp"],
"enabled": true,
"environment": {
"TOLGEE_API_KEY": "your-api-key"
}
}
}
}Any MCP client that supports STDIO servers can use the same pattern:
TOLGEE_API_KEY=your-api-key uvx tolgee-mcpIf you're running your own Tolgee instance, add the TOLGEE_API_URL environment variable:
{
"mcpServers": {
"tolgee": {
"command": "uvx",
"args": ["tolgee-mcp"],
"env": {
"TOLGEE_API_KEY": "your-api-key",
"TOLGEE_API_URL": "https://tolgee.your-domain.com"
}
}
}
}Related MCP server: Turjuman
Variable | Required | Default | Description |
| Yes | — | Your Tolgee API key |
| No |
| Base URL of your Tolgee instance |
Tool | Description |
| List all projects accessible to the authenticated user |
| Get details of a specific project |
| Create a new project |
| Update a project's settings |
| Delete a project (irreversible) |
Tool | Description |
| List all languages in a project |
| Add a new language to a project |
| Update a language's properties |
| Delete a language and all its translations |
Tool | Description |
| List localization keys with pagination |
| Search keys by name |
| Create a new key with optional translations and namespace |
| Update a key's name |
| Delete one or more keys |
| Batch import keys with translations |
Tool | Description |
| Get translations with language and pagination filters |
| Set translation values for an existing key |
| Create a key if needed and set its translations |
| Set the state of a translation (e.g. reviewed, translated) |
| Get modification history of a translation |
Tool | Description |
| Export translations (JSON, XLIFF, etc.) |
| Single-step import of translations |
Tool | Description |
| List all tags in a project |
| Add a tag to a key |
| Remove a tag from a key |
| List all used namespaces |
| Rename a namespace |
git clone https://github.com/ytarfa/tolgee-mcp.git
cd tolgee-mcp
uv sync
TOLGEE_API_KEY=your-api-key uv run tolgee-mcpMIT
Create a new localization key in a Tolgee project.
Args:
project_id: The numeric ID of the project.
name: The key name (e.g., "button.submit", "greeting.hello").
namespace: Optional namespace for the key.
translations: Optional dict mapping language tags to translation values (e.g., {"en": "Hello", "fr": "Bonjour"}).
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| name | Yes | ||
| namespace | No | ||
| translations | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains the optional namespace and translations parameters, including an example for translations. However, it does not disclose key creation behavior (e.g., whether duplicate keys are rejected, permissions needed, or side effects).
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 concise and well-structured, with a clear purpose statement followed by parameter documentation in a typical Args format. No extraneous information; every sentence adds value.
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 complexity of 4 parameters and no annotations, the description covers parameter semantics well but lacks usage guidelines and behavioral context (e.g., error conditions, idempotency). The presence of an output schema partially compensates for return value information.
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 0%, so the description must add meaning. It does so effectively by explaining each parameter: project_id is numeric names with examples, namespace is optional, translations is an optional dict mapping language tags to values. This adds significant value beyond the schema's type info.
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's purpose: 'Create a new localization key in a Tolgee project.' It specifies the verb 'create' and the resource 'localization key', distinguishing it from sibling tools like create_language or delete_keys.
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 guidance on when to use this tool vs alternatives. It does not mention prerequisites, when to prefer create_key over update_key or import_keys, or any workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a new language to a Tolgee project.
Args:
project_id: The numeric ID of the project.
name: Display name of the language (e.g., "French").
tag: BCP 47 language tag (e.g., "fr", "de", "ja").
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| name | Yes | ||
| tag | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states the action without disclosing side effects, idempotency, error behavior, or required permissions. Minimal transparency.
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?
Short and to the point: one-line summary plus concise argument descriptions. Front-loaded. Could improve structure with clearer separation but 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?
Covers purpose and parameters, but lacks info on conflict behavior, validation, or differentiation from update_language. Given output schema exists, return value explanation is unnecessary, but completeness is still moderate.
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 has 0% coverage, but description explains each parameter: project_id as numeric ID, name as display name, tag as BCP 47 tag (with examples). Adds meaningful context beyond the schema's type/name.
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 action ('Add a new language') and the resource ('to a Tolgee project'). It distinguishes from sibling tools like create_key or create_project because it specifically targets language creation.
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?
No guidance on when to use this tool versus alternatives (e.g., update_language) or prerequisites (e.g., project must exist). Implies usage but lacks explicit when-to or when-not-to context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a key if it doesn't exist and set its translations. If the key already exists, update its translations.
Args:
project_id: The numeric ID of the project.
key_name: The key name.
translations: Dict mapping language tags to translation text values.
namespace: Optional namespace for the key.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| key_name | Yes | ||
| translations | Yes | ||
| namespace | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It fails to disclose whether translations are merged or overwritten, potential side effects on existing data, authentication requirements, or rate limits. The ambiguity of 'set its translations' is a significant gap.
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 front-loaded with the core action, followed by a clear args list. Each sentence adds value, though the args list could be integrated more concisely. Overall, it's well-structured without waste.
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 output schema exists, return values are covered. However, the description lacks critical behavioral details like merge vs replace semantics, error behavior (e.g., project not found), or handling of missing translations. It partially compensates for the schema's 0% coverage but not fully.
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 schema has 0% description coverage, so the description must compensate. It adds meaning by explaining that project_id is numeric, translations is a dict mapping language tags to text values, and namespace is optional. This clarifies the schema's generic 'object' type for translations.
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 explicitly states it creates a key if missing and sets translations, or updates if key exists. This clearly distinguishes from sibling tools like create_key (create only) and set_translations (likely update only).
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 clearly indicates when to use the tool (for creation or update of translations). However, it doesn't explicitly state when not to use it (e.g., if only need to update without creating) or mention alternatives like set_translations for updates only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Tolgee project.
Args:
name: The name for the new project.
base_language_tag: BCP 47 language tag for the base language (default: "en").
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| base_language_tag | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'create' (mutation). No disclosure of side effects, permissions, or limits.
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-line docstring, front-loaded purpose, no wasted words. Efficient for a simple tool.
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?
Covers parameters well but lacks context on when to use this vs other project tools. Output schema exists, so return values need not be described. Adequate for a creation tool but missing sibling differentiation.
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?
With 0% schema coverage, description adds value: explains 'name' as project name and 'base_language_tag' as BCP 47 tag with default. Schema only provides types.
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?
Description clearly states 'Create a new Tolgee project' with a specific verb and resource. It distinguishes from sibling tools like 'create_key' or 'create_language'.
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?
No guidance on when to use this tool vs alternatives like 'update_project'. No prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete one or more localization keys from a Tolgee project.
Args:
project_id: The numeric ID of the project.
key_ids: List of key IDs to delete.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| key_ids | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It only states 'Delete' with no details on consequences, irreversibility, permissions, or side effects. For a destructive tool, this is insufficient.
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?
Extremely concise: two sentences plus bullet-style Args. No extraneous information; every word serves a purpose.
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 complexity (delete operation) and presence of output schema (not described), the description omits return value, idempotency, and differentiation from siblings. Parameter descriptions are sparse, leaving gaps for agent decision-making.
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 has 0% description coverage, so description adds value by naming parameters: 'project_id: numeric ID' and 'key_ids: list of key IDs'. Explanations are minimal but cover required fields, though lacking depth (e.g., how to obtain key IDs).
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?
Description clearly states 'Delete one or more localization keys from a Tolgee project', specifying the verb (delete) and resource (localization keys). Among sibling tools like delete_language and delete_project, it distinctly identifies the target resource.
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?
No guidance on when to use this tool versus alternatives like delete_project or update_key. No mention of prerequisites, scenarios, or conditions for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a language from a Tolgee project. This removes all translations for this language.
Args:
project_id: The numeric ID of the project.
language_id: The numeric ID of the language to delete.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| language_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description notes that deletion removes all translations, which is a key behavioral trait. However, with no annotations, it should disclose more (e.g., reversibility, permissions, side effects).
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 concise sentences plus an inline args list. The args list is somewhat redundant given the schema, but the overall structure is clean and front-loaded.
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?
With no annotations and a destructive operation, the description lacks essential context like whether the deletion is permanent, cascading effects, or required permissions.
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 0%, so the description bears the burden. It only restates the parameter names and types ('numeric ID'), which adds minimal value beyond the schema's integer type.
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 action 'Delete a language' and the resource 'from a Tolgee project', with the consequence 'removes all translations'. It distinguishes from siblings like create_language and update_language.
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?
No guidance on when to use this tool versus alternatives (e.g., disabling a language). No prerequisites or conditions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a Tolgee project. This action is irreversible.
Args:
project_id: The numeric ID of the project to delete.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only mentions irreversibility but does not disclose other behavioral traits such as permissions required, cascading effects, or rate limits. For a delete operation, more details about impact on associated data would be helpful.
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 concise with two sentences and an Args block. It front-loads the key information (delete and irreversibility). The Args block is slightly verbose for a single parameter but adds clarity.
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?
The tool has one simple parameter and an output schema exists, so return values are documented. The description covers purpose, parameter, and irreversibility. For such a simple tool, it is sufficiently complete, though adding what happens to associated resources would be beneficial.
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 0%, but the description compensates by detailing the parameter in an Args block: 'project_id: The numeric ID of the project to delete.' This fully explains the parameter's purpose and type, which the schema lacks.
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 explicitly states 'Delete a Tolgee project', which clearly identifies the action (delete) and resource (project). It distinguishes from sibling tools like delete_keys and delete_language by specifying the resource as a project.
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 warns that the action is irreversible, implying caution. However, it does not explicitly state when to use this tool versus alternatives or when not to use it. The context is clear enough for a straightforward delete operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export translations from a Tolgee project.
Args:
project_id: The numeric ID of the project.
format: Export format. Supported: "JSON" (default), "XLIFF", "PO", "APPLE_STRINGS_STRINGSDICT", "ANDROID_XML", "FLUTTER_ARB", "PROPERTIES", "YAML_RUBY".
languages: Optional list of language tags to export (e.g., ["en", "fr"]). Exports all languages if not specified.
filter_namespace: Optional namespace to filter exported keys.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| format | No | JSON | |
| languages | No | ||
| filter_namespace | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks information about behavioral traits such as whether the export is read-only (non-destructive), any required permissions, or rate limits. Since no annotations are provided, the description should disclose these traits, but it only describes parameters. The export is likely safe, but this is not stated.
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 concise, using a clear structure: a one-sentence purpose followed by parameter explanations. Each sentence earns its place with no redundant or vague 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?
The description covers all parameters thoroughly, and an output schema exists, so return values need not be described. However, it lacks context like error handling or prerequisites (e.g., project existence). Overall, it is largely complete for the tool's simplicity.
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 has 0% parameter description coverage, so the description fully compensates by explaining each parameter: project_id (numeric ID), format (supported formats listed), languages (optional list of language tags), and filter_namespace (optional namespace filter). It also mentions defaults, adding significant value 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?
The description clearly states 'Export translations from a Tolgee project.' This provides a specific verb (export) and resource (translations), making the tool's purpose immediately understandable and distinct from sibling tools like create_key or import_translations.
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 the tool is for exporting translations but does not explicitly state when to use it vs. alternatives, such as when a different export format is needed or when to use import tools instead. No exclusion criteria are provided, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific Tolgee project.
Args:
project_id: The numeric ID of the project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It does not disclose error handling (e.g., behavior for missing project_id), authentication requirements, rate limits, or any side effects. The output schema exists but is not referenced.
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 very short (two sentences) and front-loaded with the core purpose. The Args section adds structure. No wasted words, though slightly more detail could be provided without losing conciseness.
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 tool's simplicity (single parameter, output schema exists), the description is minimally adequate. However, it lacks context on common scenarios like error handling or performance, making it less complete for an agent to handle edge cases.
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 0%, but the description adds basic meaning to the single parameter: 'The numeric ID of the project.' This clarifies the type (numeric) beyond the schema's 'integer' tag, but remains minimal.
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 action ('Get details') and the resource ('a specific Tolgee project'). It is specific enough to distinguish from sibling tools like list_projects and update_project.
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 guidance on when to use this tool versus alternatives, such as list_projects for browsing or update_project for modifying. No context on prerequisites or exclusions is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the modification history of a specific translation.
Args:
project_id: The numeric ID of the project.
translation_id: The numeric ID of the translation.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| translation_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must bear full burden. It only indicates a read operation but does not disclose any behavioral traits (e.g., rate limits, error handling, or what happens if the translation doesn't exist).
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 short and front-loaded with the purpose. Two sentences efficiently convey the core action and parameters, with no unnecessary words.
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 tool's low complexity (2 required params, output schema exists), the description is minimally adequate. However, it would benefit from mentioning that it returns a history log and any prerequisites (e.g., existence of translation).
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 0%, so the description should compensate. It merely repeats parameter names and says they are 'numeric IDs', which is already in the schema (integer type). It adds little extra meaning.
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 'Get the modification history of a specific translation,' which specifies the verb and resource. It distinguishes from siblings like 'get_translations' by focusing on history.
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?
No guidance on when to use this tool versus alternatives such as 'get_translations' or 'set_translations'. The description lacks any when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get translations for keys in a Tolgee project.
Args:
project_id: The numeric ID of the project.
languages: Optional list of language tags to filter by (e.g., ["en", "fr"]). If not specified, all languages are returned.
page: Page number (0-indexed, default 0).
size: Number of items per page (default 20).
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| languages | No | ||
| page | No | ||
| size | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It explains pagination (page, size) and optional language filtering, but does not mention authentication requirements, rate limits, error behavior (e.g., missing project), or that it is read-only. While the pagination details are helpful, more behavioral context would be beneficial.
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 extremely concise: a single sentence stating the tool's purpose plus a structured Args list. Every sentence provides necessary information without redundancy. The format is front-loaded and easy to parse.
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 that an output schema exists (confirmed by context), the description need not detail return values. It covers all parameters adequately. However, it does not address potential errors or edge cases. For a relatively simple retrieval tool, it is mostly complete, but could mention that the output structure is defined by the output schema.
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 schema has 0% description coverage, so the description must compensate. It explains each parameter: project_id as numeric ID, languages as optional list of tags with behavior when omitted, page as 0-indexed with default, size as default 20. This adds significant meaning beyond the raw schema, which lacks descriptions.
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 retrieves translations for keys in a Tolgee project. It specifies the action ('get') and the resource ('translations'), and it differentiates from sibling mutation tools like set_translations or create_or_update_translations. The verb 'Get' and resource 'translations' make the purpose unambiguous.
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 clear parameter explanations and default values, but does not explicitly state when to use this tool versus alternatives like search_keys or export_translations. The context of a read operation is implicit, but no direct guidance on when not to use it is given. However, the Args section effectively describes usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import localization keys with translations into a Tolgee project.
Each key object should have a "name" field and a "translations" dict mapping language tags to values.
Args:
project_id: The numeric ID of the project.
keys: List of key objects, each with "name" (str) and "translations" (dict of language_tag -> value).
Example keys format:
[{"name": "greeting", "translations": {"en": "Hello", "fr": "Bonjour"}}]
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| keys | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but omits critical behavioral details. It does not disclose handling of duplicate keys (overwrite vs. error), whether partial failures are possible, required permissions, or idempotency. This is a significant gap for a mutation tool.
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 well-organized with clear sections (Args, Example) and an example that aids understanding. It is appropriately sized for the tool's complexity, though the example could be condensed.
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 moderate complexity, no annotations, and a schema with 0% description coverage, the description adequately covers parameter semantics and provides an example. However, it lacks completeness in behavioral aspects (error handling, output format, permissions) and does not leverage the existing output schema to explain return values.
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 0%, so the description compensates well. It explains that 'project_id' is numeric and 'keys' is a list of objects with 'name' and 'translations' fields, adding meaning beyond the minimal schema. However, it could further clarify the 'translations' dictionary structure (e.g., expected language tags).
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 imports localization keys with translations into a Tolgee project. However, it does not differentiate from the sibling tool 'import_translations', which may have similar behavior, reducing clarity slightly.
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?
No explicit guidance on when to use this tool versus alternatives like 'create_key' (single key creation) or 'import_translations'. The description assumes bulk import but doesn't state this or provide criteria for choosing among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import translations into a Tolgee project using single-step import.
Each key object should have a "name" and "translations" mapping language tags to values.
Args:
project_id: The numeric ID of the project.
keys: List of key objects with "name" (str) and "translations" (dict of language_tag -> value).
Example:
[{"name": "hello", "translations": {"en": "Hello", "de": "Hallo"}}]
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| keys | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Lacks disclosure of side effects like overwriting existing translations, idempotency, or error handling. Annotations absent, so description should provide more behavioral context.
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?
Concise with three sentences plus Args and example. The example is helpful, but the structure could be more formal. Yet no unnecessary content.
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?
Covers parameters adequately but misses return value description and usage context. With output schema present, return details could be omitted, but still lacks error handling and conflict behavior.
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 has 0% description coverage, but description explains project_id as numeric and keys as list of objects with 'name' and 'translations' structure, adding value beyond the loose schema definition.
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 imports translations into a Tolgee project using a single-step import, distinguishing it from siblings like import_keys or create_or_update_translations.
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?
No guidance on when to use this tool versus alternatives. With many sibling tools, this omission reduces clarity for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List localization keys in a Tolgee project.
Args:
project_id: The numeric ID of the project.
page: Page number (0-indexed, default 0).
size: Number of keys per page (default 20).
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| page | No | ||
| size | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, rate limits, data freshness, or pagination boundaries beyond defaults. The agent gets no extra safety or behavior info.
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 short and front-loaded, but includes a Python-style 'Args:' block that is somewhat redundant since parameters are already in the schema. Still, it is efficient and clear.
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 an output schema exists (not shown), the description doesn't need to cover return values. However, it omits any mention of filtering, ordering, or other common listing features, which leaves gaps for an agent deciding to use this tool over siblings.
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 0%, but the description clarifies that page is 0-indexed and provides default values. This adds value beyond the schema's names and types. However, for a simple 3-parameter tool, the description adds adequate meaning.
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 'List localization keys in a Tolgee project', specifying the verb (list) and resource (localization keys in a project). This distinguishes it from sibling tools like search_keys or get_translations.
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 basic parameter details (project_id required, page/size defaults) but no guidance on when to use this tool versus alternatives like search_keys. No when-not-to-use or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all languages configured in a Tolgee project.
Args:
project_id: The numeric ID of the project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the basic function and parameter, omitting details like error behavior, permissions, or return characteristics (though output schema 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?
The description is extremely concise, using two sentences to state purpose and parameter. It is front-loaded with the main function and contains no unnecessary words.
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 tool with one parameter and an output schema, the description is minimally adequate. It lacks context on filtering, ordering, or error scenarios, but the output schema may compensate for return format.
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 0%, so the description must compensate. It adds 'The numeric ID of the project' to the project_id parameter, providing clarity beyond the schema's type integer, but does not elaborate further.
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 'List all languages configured in a Tolgee project', specifying the verb (list), resource (languages), and scope (all in a project). It effectively distinguishes from sibling tools like create_language and delete_language.
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 usage by requiring project_id but lacks explicit when-to-use or when-not-to-use guidance. No alternatives or exclusions are mentioned, making it adequate but not proactive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all used namespaces in a Tolgee project.
Args:
project_id: The numeric ID of the project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. The description implies a read operation ('List'), but does not explicitly state it is read-only, mention consequences, or disclose any restrictions. Given the simplicity, it is adequate but lacks explicit behavioral traits.
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 two sentences, each adding value: first states the purpose, second describes the parameter. No extraneous words, front-loaded, and 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 simple tool with one parameter and an output schema, the description is mostly complete. It explains the action and the argument. However, it could clarify what 'used' means (e.g., namespaces with at least one key) and confirm return type (though output schema exists).
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 description adds meaning beyond the schema for the single parameter 'project_id' by describing it as 'The numeric ID of the project.' This clarifies its purpose, compensating for the 0% schema description coverage.
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 all used namespaces in a Tolgee project. The verb 'list' and resource 'namespaces' are specific, and it distinguishes from sibling list tools (e.g., list_keys, list_languages) by naming the resource.
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?
No guidance on when to use vs alternatives. The description only states what it does and the argument, omitting any context about when it is appropriate (e.g., to get an overview of namespaces) or when other tools like get_project or search_keys might be more suitable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Tolgee projects accessible to the authenticated user.
Returns a list of projects with their IDs, names, and base language.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It indicates a read operation with no side effects, but fails to disclose authentication needs or potential issues. For a simple list tool, it is adequate but not exhaustive.
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, no wasted words. First sentence defines purpose, second describes output. Ideal structure.
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?
The tool is simple (no parameters, no nested objects) and has an output schema. The description is complete and adds the key information about returned fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description adds value by clarifying the output fields (IDs, names, base language), which goes 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?
The description clearly states the verb 'list' and resource 'projects', and specifies scope 'accessible to the authenticated user'. It distinguishes from siblings like 'get_project' (single project) and 'create_project'.
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 usage for listing all projects but provides no explicit when-to-use or when-not-to-use compared to other tools like 'get_project'. No alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags in a Tolgee project.
Args:
project_id: The numeric ID of the project.
page: Page number (0-indexed, default 0).
size: Number of tags per page (default 20).
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| page | No | ||
| size | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description only states the purpose without disclosing behavioral traits like read-only nature, authorization needs, or error handling. The listing behavior is implied but not explicitly confirmed.
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 extremely concise: one sentence for purpose and a short list for parameters. No unnecessary words or redundant information.
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 presence of an output schema, return values are covered. The description covers parameters and basic behavior, though it could mention ordering or pagination nuances for full completeness.
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?
With 0% schema coverage, the description compensates by explaining each parameter: project_id ('numeric ID'), page ('0-indexed, default 0'), and size ('default 20'). This adds meaning beyond the schema's type/default fields.
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 'List all tags in a Tolgee project' with a specific verb and resource, but does not explicitly differentiate from sibling tools like list_keys or list_projects, though the resource name 'tags' implies the distinction.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., searching or filtering by key). The description lacks any context for appropriate usage or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a tag from a localization key.
Args:
project_id: The numeric ID of the project.
key_id: The numeric ID of the key.
tag_id: The numeric ID of the tag to remove.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| key_id | Yes | ||
| tag_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose side effects, permissions, error conditions, or what happens if the tag is not attached. Minimal behavioral information.
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 very concise with a single sentence and an Args block. The Args block is somewhat redundant with the schema, but the overall length is appropriate.
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 removal tool, the description covers the basic action. However, it lacks prerequisites, error handling, and usage context. The presence of an output schema reduces the need to describe return values.
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 Args section adds 'The numeric ID of the ...' which provides slightly more context than the schema titles alone, but does not explain how to obtain the IDs or their relationships.
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 name and description clearly state the action: remove a tag from a localization key. It distinguishes from the sibling tool 'tag_key' which adds a tag.
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?
No guidance on when to use this tool vs alternatives, no preconditions or context provided. The description only states the action without any help on decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for localization keys by name in a Tolgee project.
Args:
project_id: The numeric ID of the project.
search: Search query string to match against key names.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| search | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It only states it performs a search (implying read-only), but does not disclose any traits such as idempotency, rate limits, or side effects. This is insufficient for a tool with zero 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of one sentence for the purpose and two bullet points for parameters. Every word is necessary and no fluff exists. It is well-structured and front-loaded.
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 tool's simplicity (2 required parameters, no nested objects, and an output schema), the description covers the essential information: what the tool does and its inputs. It does not mention pagination or result limits, but the output schema likely handles that. For a search tool, it is adequately 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?
The input schema has 0% description coverage (only titles), but the description adds meaningful explanations: 'The numeric ID of the project' for project_id and 'Search query string to match against key names' for search. This adds value beyond the schema's titles.
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 'Search for localization keys by name in a Tolgee project,' specifying the verb (search) and resource (localization keys). This distinguishes it from siblings like list_keys (which lists all keys) and import_keys (which imports keys).
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 needing to find keys by name) through its parameters, but does not explicitly state when not to use it or mention alternative tools like list_keys or search alternatives. Usage context is clear but guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set translation values for an existing key in a Tolgee project.
Args:
project_id: The numeric ID of the project.
key_name: The name of the existing key.
translations: Dict mapping language tags to translation text values (e.g., {"en": "Hello", "fr": "Bonjour"}).
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| key_name | Yes | ||
| translations | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only says 'set translation values', which implies mutation. It fails to disclose whether it overwrites or merges translations, error behavior for missing keys, idempotency, authorization needs, or rate limits.
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 concise with a two-sentence overview plus an args list. It is front-loaded with the purpose. Every sentence adds value, though the args section could be more 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?
Despite having an output schema (not shown), the description omits return value details, error conditions, and behavioral traits (merge vs overwrite). For a mutation tool, more context is needed to be fully self-contained.
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 0% (no description in schema), so the description must compensate. It provides brief yet clear explanations for all three parameters, including an example for 'translations'. However, it lacks constraints like key existence validation or format specifics.
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 action ('Set translation values') and target ('existing key in a Tolgee project'), using a specific verb+resource pattern. It implicitly distinguishes from sibling tools like 'create_key' or 'create_or_update_translations', but does not explicitly differentiate from the latter.
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 only states the basic context ('existing key') but provides no guidance on when to use this tool versus alternatives like 'create_or_update_translations', nor does it mention prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the state of a specific translation.
Args:
project_id: The numeric ID of the project.
translation_id: The numeric ID of the translation (not the key ID).
state: The new state. Valid values: "UNTRANSLATED", "TRANSLATED", "REVIEWED".
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| translation_id | Yes | ||
| state | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It lacks details on idempotency, side effects (e.g., whether it overwrites existing state), or what happens on invalid input. The presence of an output schema is not mentioned.
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 clear and well-structured, but the 'Args' section adds verbosity. Could be more concise while retaining clarity.
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 complexity (3 required params, mutation) and absence of annotations, the description is adequate but incomplete. It does not mention return value, error behavior, or output schema, which would aid agent decision-making.
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 0%, so description compensates by explaining all three parameters: clarifies translation_id is not key ID, and lists valid state values. This adds significant meaning beyond the schema, though some numeric parameter constraints are missing.
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 verb 'Set' and the resource 'state of a specific translation', distinguishing it from batch tools like set_translations. It also lists valid states.
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 mentions valid states but does not explicitly state when to use this tool versus alternatives like set_translations. No exclusion criteria or prerequisites are given, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a tag to a localization key. Creates the tag if it doesn't exist.
Args:
project_id: The numeric ID of the project.
key_id: The numeric ID of the key to tag.
tag_name: The name of the tag to add.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| key_id | Yes | ||
| tag_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially reveals behavior (tag creation if absent) but omits details like whether multiple tags can be added at once, permission requirements, or side effects on existing tags.
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 short and includes an Args section for parameter details. It is front-loaded with the core action, though some minor redundancy exists.
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 simple parameters and existing output schema, the description covers the essential aspects of the operation. It lacks mention of return values or error handling, but that may be covered by the output schema.
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?
Despite 0% schema description coverage, the description provides a clear one-line explanation for each parameter (project_id, key_id, tag_name), adding meaning beyond the schema's type definitions.
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 action (add a tag to a localization key) and the behavior (creates tag if it doesn't exist), distinguishing it from the sibling 'remove_tag_from_key'. However, it could be more specific about the concept of 'tag'.
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?
No guidance is provided on when to use this tool versus alternatives like 'create_key' or 'list_tags'. No prerequisites or conditions are mentioned, leaving the agent without context for proper selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a localization key's name.
Args:
project_id: The numeric ID of the project.
key_id: The numeric ID of the key to update.
name: The new name for the key.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| key_id | Yes | ||
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose all behavioral traits. It states the update action but does not mention side effects (e.g., impact on translations), required permissions, or constraints like name uniqueness. This is insufficient for a mutation tool.
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 short and front-loaded with the main purpose. The Args section is a bit redundant with the schema, but overall it is efficient with no unnecessary words. Could be slightly more concise.
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?
With 3 parameters all documented and an output schema present (not shown), the description covers the basics. However, it lacks contextual details like common errors, validation rules (e.g., name format), or whether the key must exist. Falls short of full completeness.
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 0%, so the description must add meaning. It explains each parameter: project_id (numeric project ID), key_id (numeric key ID), name (new name for the key). This provides clear semantics beyond the schema's type-only definitions.
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 'Update a localization key's name,' providing a specific verb and resource. It distinguishes from sibling tools like 'create_key' (which creates) and 'delete_keys' (which deletes), so the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when renaming a key but lacks explicit instructions on when to use this tool versus alternatives, such as when to create a new key instead. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a language's properties in a Tolgee project.
Args:
project_id: The numeric ID of the project.
language_id: The numeric ID of the language to update.
name: The new display name for the language.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| language_id | Yes | ||
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It only states 'Update' (mutation) without any details on side effects, idempotency, permissions, or limits. This is insufficient.
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 extremely concise: one sentence and three bullet points. No redundant information; every part is necessary.
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 simplicity (3 params, output schema exists), the description is largely complete. However, it implies multiple updatable properties but only lists 'name', which could be clarified.
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 description provides explicit meanings for all three parameters ('The numeric ID of the project', etc.), which adds value beyond the schema's titles. However, it lacks constraints like uniqueness or character limits.
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 action ('Update') and resource ('language's properties in a Tolgee project'), which distinguishes it from siblings like create_language, delete_language, and list_languages. However, it lacks explicit scope or alternative differentiation that would merit a 5.
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?
No guidance is provided on when to use this tool versus alternatives. The description simply states what it does without any when-to-use or when-not-to-use information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a namespace in a Tolgee project.
Args:
project_id: The numeric ID of the project.
namespace_id: The numeric ID of the namespace to rename.
name: The new name for the namespace.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| namespace_id | Yes | ||
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as whether the operation is destructive, idempotent, or requires authorization. The description only lists parameters without additional context.
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 short and front-loads the purpose. However, the args list is somewhat repetitive and could be more concise. Overall, it is efficient but not maximally concise.
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 that there is an output schema (not shown) and 3 parameters, the description is minimal. It omits expected output, constraints (e.g., name uniqueness), error conditions, and any side effects. Without annotations, this is inadequate.
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 0%, so the description must explain parameters. It adds minimal context (e.g., 'The numeric ID of the project'), but essentially restates the parameter names. This is insufficient to fully compensate for the lack of schema descriptions.
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 'Rename a namespace in a Tolgee project', specifying the action (rename) and the resource (namespace). It is distinct from sibling tools, none of which modify namespaces.
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?
No guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. Sibling tools like create_key or update_language are not differentiated in usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing Tolgee project's settings.
Args:
project_id: The numeric ID of the project to update.
name: The new name for the project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only says 'update settings' but only mentions the name parameter, implying other settings may be involved. It does not disclose validation behavior, atomicity, or side effects.
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?
Extremely concise: one sentence plus parameter list. Every word is necessary and front-loaded. No wasted space.
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 update tool with only two parameters and output schema available, the description covers purpose and parameter meanings. It is nearly complete, though could mention that only the name field is updatable.
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 0%, but the description adds meaning: 'numeric ID' for project_id and 'new name' for name. This is adequate but minimal.
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 'Update an existing Tolgee project's settings,' specifying the verb (update) and resource (project settings). It lists the two parameters, distinguishing it from create_project (creates new) and get_project (reads).
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?
No guidance on when to use this tool vs alternatives (e.g., create_project, delete_project). It does not specify prerequisites like needing the project ID or whether the project must already exist.
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. Dates show when Glama detected each change.
v0.1.0create_keycreate_languagecreate_or_update_translationscreate_projectdelete_keysdelete_languagedelete_projectexport_translationsget_projectget_translation_historyget_translationsimport_keysimport_translationslist_keyslist_languageslist_namespaceslist_projectslist_tagsremove_tag_from_keysearch_keysset_translation_stateset_translationstag_keyupdate_keyupdate_languageupdate_namespaceupdate_projectMost tools have distinct purposes, but there is notable overlap between import_keys and import_translations (both import keys with translations), and between create_key, create_or_update_translations, and set_translations (all handle key creation/updates with translations). This could cause selection errors.
Tool names overwhelmingly follow a consistent verb_noun pattern (e.g., create_key, list_projects, update_language). The only minor exception is 'create_or_update_translations' which includes 'or', but the pattern is clear and uniform across all tools.
With 27 tools, the server is on the heavier side. While the localization domain is rich, there is some redundancy (e.g., import_keys vs import_translations, create_key vs create_or_update_translations) suggesting potential for consolidation. The count feels slightly excessive.
CRUD operations are well-covered for projects, languages, keys, and translations, including tagging, namespaces, and import/export. A minor gap is the lack of a dedicated 'get_key' tool (key retrieval is indirect via get_translations or list_keys), but overall the surface is fairly complete.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for Crowdin — projects, files, strings, translation progress, tasks, and members.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Lingo.dev MCP Server - World-class i18n implementation with ICU MessageFormat.
Translate MCP — wraps LibreTranslate API (https://libretranslate.com/)
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ytarfa/tolgee-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
