Tolgee

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It adds useful context about forking behavior and the enterprise constraint, but it does not disclose potential side effects, permission requirements, or return values, which are expected 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 two sentences with no fluff, front-loading the essential action and then adding a key constraint. Every word 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 3-parameter tool with no output schema and no annotations, the description provides the core purpose and a critical prerequisite, but it omits details like response format or behavior when branching is not enabled. It is adequate but not fully comprehensive.

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 parameters have schema descriptions (100% coverage), so the baseline is 3. The description mentions 'forking from an existing branch,' which aligns with originBranchId but adds no new information beyond the schema's existing parameter description.

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 'Create a new branch in a Tolgee project by forking from an existing branch,' specifying the verb and resource. It distinguishes this tool from siblings like create_project and create_keys by focusing on branch 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?

The description provides a clear constraint: 'Only available for projects with branching enabled (enterprise feature),' which tells users when not to use it. However, it does not explicitly name alternatives or provide broader when-to-use guidance beyond this prerequisite.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the critical behavior that existing keys are silently skipped and their translations/tags are not updated. It also directs users to update tools. It doesn't mention authentication or error scenarios, but these are partially covered in the schema (e.g., projectId requirement).

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, front-loaded with the purpose and followed by vital behavioral context and alternative tools. Every word earns its place with no redundancy or fluff.

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 creation tool with 4 parameters fully documented in the schema, the description covers the essential behavior (skip existing keys) and provides guidance for alternative tools. It doesn't describe return values, but no output schema exists. The description is sufficient for selection and invocation, though it could mention the branch/namespace options 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?

Schema description coverage is 100%, so the baseline is 3. The description mentions optional translations and tags, which aligns with the schema, but adds no extra parameter semantics beyond what the schema already provides. The skip behavior is not a parameter detail.

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 creates translation keys in a Tolgee project with optional translations and tags. It distinguishes itself from sibling tools by explicitly naming update_key and set_translation as alternatives for modifying existing 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?

It explicitly says when to use this tool (to create keys) and when not to (keys that already exist are skipped). It names specific alternative tools for modifying existing keys, providing clear decision guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action ('add a new language') without revealing side effects, authentication requirements, error behavior, or idempotency. For a mutation tool, this 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 a single, front-loaded sentence that is succinct and has no wasted words. It clearly conveys the core action in the fewest possible words without omitting necessary context.

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?

This is a simple create tool with fully documented parameters and no output schema. The description plus schema are adequate for basic usage, but it lacks behavioral context (e.g., duplicate handling, required authentication context). It is not comprehensive but acceptable for a straightforward creation operation.

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 fully documents all 5 parameters. The description adds no parameter-specific meaning beyond restating the purpose. The baseline of 3 applies because the schema handles the details and the description does not contradict it.

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 is specific: 'Add a new language to a Tolgee project' clearly identifies the verb (add), the resource (language), and the scope (Tolgee project). It distinguishes from sibling tools like create_branch, create_keys, and create_project by naming the target entity.

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: one would use this when adding a language to a project. However, it does not explicitly state when to use this over alternatives, mention prerequisites (e.g., projectId for PAT), or note exclusions. Basic context is clear but no additional guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the primary action and does not mention side effects, permissions, prerequisites (e.g., organization must exist), or reversibility—significant gaps for a creation operation.

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 conveys the action and key context with no unnecessary words. It is both concise 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?

The schema fully documents all parameters, and the description covers the tool's core purpose. However, without an output schema, the description does not indicate what the tool returns or how errors are handled, leaving some completeness gaps for a creation tool.

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 all parameters clearly described in the schema. The tool description adds no additional parameter-level meaning beyond what is already available, so the baseline score 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 action: 'Create a new Tolgee project with initial languages'. It specifies a concrete verb and resource, making it easy to distinguish from sibling tools like create_branch 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?

The description provides clear context: this tool is for creating a new project and setting its initial languages. However, it does not explicitly mention when not to use it or mention alternatives like create_language for existing projects, so it falls just short of full guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states that the action is destructive and imposes a mandatory user-confirmation step, which are key behavioral traits. It does not detail side effects or error cases, but covers the most critical 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 two concise sentences, with the purpose stated first and the warning following. Every word earns its place, and it is instantly scannable.

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 delete operation with two parameters and no output schema, the description is adequately complete. It provides purpose, destructive context, and a usage constraint (confirmation). It lacks detail on failure modes or prerequisites, but given the tool's simplicity, this is acceptable.

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 both projectId and branchName already well-described in the input schema. The description adds no additional parameter semantics, so a baseline score 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 'Delete a branch from a Tolgee project' with a specific verb (delete) and resource (branch). This distinguishes it from sibling tools like delete_keys, making its 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 explicit usage guidance by emphasizing that the operation is destructive and that the assistant must always confirm with the user before calling. It does not mention alternatives or exclusions, but the destructive warning effectively frames when this tool is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It explicitly warns that the operation is destructive and requires user confirmation, which is crucial behavioral context. It doesn't detail irreversibility or authorization, but the destructive flag is meaningful.

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: the first states the purpose, the second adds a critical safety warning. Every word earns its place, with no redundancy or fluff.

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 destructive tool with 4 parameters and no output schema, the description covers the essential context: what it does and the safety precaution. It doesn't explain return values or side effects, but those are less critical given the explicit destructive warning and complete parameter 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?

Schema description coverage is 100%, so the baseline is 3. The tool description adds no parameter-specific information beyond what the schema already provides, so it neither enhances nor detracts from the schema's clarity.

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 deletes translation keys from a Tolgee project, using a specific verb and resource. It is distinguishable from siblings like delete_branch based on the resource type, though it doesn't explicitly call out alternatives.

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 context: it is a destructive operation and the AI must confirm with the user before calling. It doesn't mention alternatives or when not to use it, but the confirmation requirement is a strong usage guideline.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. 'Poll for completion' implies a non-mutating, repeated-read behavior, but the description does not disclose return format, status values, or any potential side effects. This is adequate but minimal.

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 exactly two sentences, front-loaded with the core action, and every word contributes value. No wasted 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?

Given the tool's simplicity (2 params, no output schema), the description covers the main purpose and usage. However, it omits return value details or hints about possible statuses, which could be necessary for an agent to interpret the response correctly. This leaves a minor gap in 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?

The input schema provides 100% coverage with descriptions for both jobId and projectId. The description adds no additional semantics beyond what the schema already states, so the baseline score 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 states a specific action ('Get the status') and resource ('batch job') with an identifying criterion ('by its ID'). It also provides a concrete example ('e.g. machine translation'), clearly distinguishing it from sibling tools like get_translations or machine_translate.

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 'Use to poll for completion' explicitly explains when this tool should be used. While it does not mention alternatives or exclusions, the usage context is clear and relevant for a polling scenario.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It clarifies that the tool returns metadata only (not translations), which is useful, but it does not mention error behavior, permissions, or side effects. For a simple read operation this is acceptable, but gaps remain.

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: the first states the core purpose and return fields, the second gives a pointer to an alternative. Every word contributes, with no redundancy or fluff.

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 get tool with no output schema, the description adequately explains what is returned (metadata fields) and directs users to get_translations for translations. It could mention optionality of branch/projectId, but the schema covers those details, so the description is sufficiently 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 descriptions cover all four parameters (100% coverage), and the description does not add additional parameter semantics beyond what the schema already provides. It reinforces keyName as the lookup key but adds no new 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 states a specific verb ('Get') and resource ('translation key's metadata'), and explicitly lists the metadata fields (name, namespace, description). It also distinguishes from the sibling tool get_translations by noting the difference, which clarifies its unique purpose.

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 an explicit alternative ('To get the key's translations, use get_translations'), giving clear guidance for a common alternative use case. However, it does not contrast with other siblings like list_keys or search_keys, so it is not fully comprehensive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It mentions the return data (translated, reviewed, untranslated percentages), which is useful, but does not disclose potential errors, authentication needs, or side effects. Since it is a read-only operation in nature, the lack of explicit safety notes is a 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 two sentences, front-loaded with the primary action, and every word contributes meaning. No redundant or vague language.

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 (one optional parameter, no output schema), the description sufficiently covers the tool's purpose and return value. It could mention the conditional requirement of projectId more explicitly, but the schema handles that. The description is adequate for an agent to understand its role.

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% for the single parameter projectId, whose description explains its purpose and auto-resolution behavior. The tool description itself adds no parameter context, so the baseline of 3 applies.

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 function: 'Get translation status and progress for each language in a project.' It specifies the resource (language statistics) and the action (get), and distinguishes it from siblings like get_translations or list_languages by focusing on per-language progress percentages.

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 needing translation progress per language, but does not explicitly specify when to prefer this over alternatives or mention exclusions. No direct comparison with sibling tools is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must disclose behavior. It accurately states that the tool returns translations in all project languages or the specified subset, which is the core behavior. However, it does not mention behavior related to branch/namespace filtering, error handling, or authentication differences (PAT vs PAK), leaving gaps.

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 short sentences, front-loaded with the verb and resource. No filler or redundancy. Every word 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?

Despite having 5 parameters and no output schema, the description only covers the basics of language filtering. It omits important context such as the roles of branch and namespace, the projectId requirement difference for PAT vs PAK, and any details about the return structure. The tool is not fully specified for an agent to invoke confidently.

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 this dimension receives the baseline of 3. The description adds no additional meaning beyond the schema; it merely echoes the languages parameter's 'all or specified' behavior already documented in the schema. No extra context is provided for other parameters like branch or projectId.

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 'Get' and resource 'translations for a specific key in a Tolgee project,' making it distinct from sibling tools like get_key (which presumably returns key metadata) and search_keys. It also explicitly describes the return scope (all languages or specified), giving a specific, actionable purpose.

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 a usage condition: use the 'languages' parameter to limit results to specified languages; otherwise it returns all languages. However, it does not provide any guidance on when to choose this tool over similar siblings like get_key or search_keys, nor does it mention exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals pagination behavior ('Returns up to 100 results per page') and a critical availability constraint (enterprise feature). While it does not detail response format or authorization, these are less critical for a read-only list operation.

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, front-loads the main purpose, and includes only essential information. Every word earns its place, and there is no redundancy or fluff.

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 list tool with no output schema, the description provides the core purpose, pagination limit, and an important enterprise constraint. It does not describe return fields, but given the simplicity and lack of output schema, this is acceptable. It is complete enough for an agent to understand the tool's behavior and limitations.

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 baseline is 3. The description adds no direct parameter guidance beyond mentioning pagination, which aligns with the page parameter. It does not elaborate on search or projectId, but the schema already describes these adequately. No additional value is provided 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 states the tool's function: 'List branches in a Tolgee project.' This is a specific verb+resource construction that distinguishes it from sibling tools like list_keys or list_languages.

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 a clear context for usage and an explicit exclusion: 'Only available for projects with branching enabled (enterprise feature).' This tells the agent when not to use the tool, though it does not mention alternatives. That qualifies as a clear usage guideline with a constraint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It mentions the pagination limit ('Returns up to 100 keys per page'), which is a key behavioral trait. However, it does not describe authentication requirements, error handling, or default branch behavior, though for a read-only list tool this is moderately comprehensive.

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 exactly two sentences, with the first clearly stating the primary purpose and the second providing pagination and an explicit alternative. Every sentence earns its place, with no wasted words or redundancy.

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 list tool with no output schema and optional parameters, the description covers the core purpose, pagination behavior, and differentiation from search_keys. It does not explain return values or what happens if projectId is omitted, but the schema and context signals fill some gaps. Overall it is adequately complete for the tool's complexity.

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 is 3. The description does not add meaningful parameter semantics beyond the schema; the pagination detail slightly informs the 'page' parameter but is largely redundant with the schema's own description. It does not compensate for any gaps because there are none.

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 translation keys in a Tolgee project' with a specific verb and resource. It also explicitly distinguishes from the sibling tool search_keys by indicating it is for listing all keys rather than searching by name/text, which differentiates it effectively.

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 explicit guidance on when to use this tool vs the alternative: 'Use search_keys to find specific keys by name or translation text.' This implies when not to use this tool (when searching for specific keys) and clarifies the appropriate use case for listing/browsing. The pagination note also sets expectations for bulk listing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a useful pagination limit ('Returns up to 1000 results per page'), but does not describe other behaviors such as response format or authentication requirements, though the schema hints at PAT/PAK 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 a single sentence that front-loads the purpose and then states a key behavioral detail about pagination. It has zero wasted words and is perfectly sized for the tool's simplicity.

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 list tool, the description provides the core purpose and a pagination detail, which covers the essential usage. However, with no output schema, it does not describe the structure of language objects, and it does not explain the PAT/PAK distinction beyond the schema's parameter description.

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 already documents both parameters (page and projectId) with detailed descriptions, so the description adds little beyond the pagination hint. With schema coverage at 100%, a 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 uses a specific verb 'List' with a clear resource 'languages configured for a Tolgee project', which makes the tool's purpose unmistakable. It also distinguishes this from sibling tools like list_keys, list_projects, and list_branches by focusing on languages.

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 states the context (listing languages for a Tolgee project), but it does not mention when to use this tool versus alternatives or any exclusions. It provides clear context but no explicit when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of behavioral disclosure. 'List' implies a read-only operation, but the description does not mention any additional behaviors such as pagination, sorting, or authentication requirements. It is adequate but lacks depth.

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 long, front-loaded with the action, and the second sentence adds useful domain context without redundancy. Every word contributes to understanding the tool's 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 the low tool complexity (1 optional parameter, no output schema), the description sufficiently covers what the tool does and the context of namespaces. It could mention the return type implicitly, but 'List all namespaces' makes it obvious. The description is 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 schema provides 100% coverage for the single parameter (projectId) with a description. The tool description does not add any parameter details beyond what the schema already explains, 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's action ('List all namespaces') and the resource ('in a Tolgee project'), and it distinguishes itself from sibling list tools (list_branches, list_keys, list_languages, list_projects) by focusing on namespaces. The additional context about namespaces organizing translation keys adds clarity.

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 should be used when you need to see all namespaces in a project. It provides context about what namespaces are, but does not explicitly mention when not to use it or mention alternatives. For a simple listing tool, this is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses pagination (up to 100 per page) and user scoping, and the verb 'List' implies a read-only operation. However, it does not explicitly state auth requirements or that no modifications occur.

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?

Single concise sentence, front-loaded with the action, no 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?

For a simple list tool with fully documented parameters and no output schema, the description includes the key pagination limit and user scoping, making it complete for the agent to invoke correctly.

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?

Both parameters are fully described in the schema (100% coverage), and the description adds no extra parameter details, so the baseline score 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 uses the specific verb 'List' with the resource 'Tolgee projects' and the scope 'accessible to the current user', clearly distinguishing it from sibling list tools like list_branches and list_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?

It gives clear context (projects accessible to the user) and includes pagination behavior, but does not explicitly state when to prefer this over other list tools or mention exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of disclosing behavior. It transparently notes pagination ('Returns up to 1000 results per page'), which is a key behavioral trait. The verb 'List' implies a read-only operation, so the safety profile is clear enough for a list tool, though it does not explicitly mention lack of 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 two short sentences, front-loaded with the primary action and followed by a useful detail. Every word earns its place; there is no redundancy or filler.

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 list tool with a well-defined schema and no output schema, the description provides sufficient context: what is listed, in what project, and the pagination behavior. It does not detail the response format, but that is not required here given the tool's simplicity. The absence of annotations is mitigated by the clear read-only nature of 'List'.

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 is 3. The description adds a little beyond the schema by clarifying the pagination limit (up to 1000 results per page), which relates to the 'page' parameter, but it does not add meaning for 'search' or 'projectId' beyond what the schema already states. Thus, it meets but does not exceed the baseline.

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 function: 'List all tags used in a Tolgee project.' This gives a specific verb ('List') and resource ('tags'), and the mention of pagination further specifies the scope. It distinguishes itself from sibling tools like list_branches or list_keys by focusing on tags.

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 context—use this when you need to list tags in a Tolgee project. It does not explicitly mention alternatives or exclusions, but the resource type (tags) is distinct among siblings, making the usage implicit. It lacks explicit 'when not to use' guidance, so it does not earn a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It discloses the asynchronous nature by mentioning a batch job ID and polling. However, it omits potential side effects (e.g., overwriting existing translations), auth requirements, or failure modes, so transparency is incomplete.

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: the first states the purpose efficiently, and the second explains the return value and the next step. There is no fluff, and the structure is front-loaded with the core 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?

Given no output schema, the description at least specifies that the return is a batch job ID and directs to the polling tool. It covers the essential workflow for an async translation trigger. However, it does not mention prerequisites like projectId for PAT (though in schema) or behavior on overlapping keys, making it slightly incomplete.

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 all five parameters described, so the baseline is 3. The description adds minimal parameter semantics beyond implying 'keys' maps to keyNames and 'target languages' to targetLanguageTags. It does not explain branch, namespace, or projectId, but the schema already does.

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 ('Start') and clearly defines the resource and action: 'machine translation for specified keys into target languages'. This distinguishes it from sibling tools like get_translations or set_translation, and the mention of a batch job ID adds operational specificity.

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 clear workflow guidance by instructing to 'use get_batch_job_status to poll for completion', which tells the agent what to do after invocation. It implies this tool is for initiating machine translation, not for manual translations, but it does not explicitly list alternatives or exclusion criteria, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry behavioral disclosure. It mentions the pagination limit (up to 50 keys per page) and the unsupported filters, which are useful. However, it does not disclose details like response format, authentication nuances beyond schema, or error behaviors, so it is adequate but not rich.

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, front-loaded with the core purpose, then adds pagination detail, and concludes with a limitation note. Every sentence adds value, and it is 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?

The tool is moderately complex with 5 parameters, but the schema fully documents them. The description provides purpose, pagination, and unsupported features, giving a solid overall picture. It could benefit from mentioning response shape or when to use list_keys instead, but it is reasonably 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%, so each parameter is already documented. The description adds marginal context by clarifying that search matches key name or translation text and that namespace/tags filtering is unsupported, which helps explain the lack of those parameters. This is a baseline with a slight bonus, but not enough to raise beyond 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 clearly states the tool's function: searching for translation keys by name or translation text. It also specifies the resource (Tolgee project) and differentiates from siblings like list_keys or get_key by focusing on search behavior.

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 context on when to use this tool (for searching) and explicitly notes the limitation that namespace and tags filtering is not yet supported, advising client-side filtering when needed. It does not name an alternative tool, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the precondition (key exists) and that it can update multiple languages, but does not clarify whether partial translation maps merge with or replace existing translations for unspecified languages. This is a notable 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?

Two concise sentences, front-loaded with the primary action and necessary prerequisite. No wasted 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 5-parameter tool with no annotations or output schema, the description gives essential context (key existence, multi-language support) but omits the update/merge behavior and return value. Still, it is functional and points to the sibling creation tool.

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%, but the description adds semantic value by stating the key must already exist, which clarifies the keyName parameter's meaning. It also affirms that translations can cover multiple languages, reinforcing the structure of the translations object.

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 'Set or update translations for a key in one or more languages', identifying the specific action and resource. It distinguishes from siblings like create_keys and update_key by focusing on translation values rather than key creation or metadata.

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 explicitly states that the key must already exist and directs the user to use create_keys first, providing clear when-to-use guidance and an alternative. This is explicit exclusion and fulfills the criterion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains the purpose and the source-code proximity criterion, but it does not disclose key behavioral traits such as whether storing relationships overwrites existing ones, whether it is idempotent, or what permissions are required. This lack of operational detail is a significant gap for a mutating 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 concise at two sentences, front-loaded with the core action, and every sentence earns its place. It states the purpose, the benefit (more consistent translations), and the usage heuristic without unnecessary filler.

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 relatively simple with three parameters and no output schema. The description covers its purpose and usage context well, but it lacks behavioral details such as overwrite semantics or whether a call returns a job ID. Given the absence of annotations and output schema, the description is reasonably complete but leaves important operational questions unanswered.

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 already provides complete descriptions for all three parameters, achieving 100% coverage. The description adds conceptual value by defining the semantics of 'related keys' (keys appearing near each other in source code), which goes beyond the schema's 'List of related keys in order'. This extra context helps the agent understand the intent behind relatedKeysInOrder.

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 ('Store key relationships') and the resource ('key relationships for Tolgee machine translation'), with a specific purpose: using related keys as context for more consistent translations. This distinguishes it from sibling tools like create_keys or get_key, which focus on individual key management.

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 a clear usage heuristic: keys that appear near each other in source code should be stored as related. This gives the agent contextual guidance on when to invoke the tool, though it does not explicitly state when not to use it or mention alternatives. The 'should be stored as related' phrasing implies the appropriate scenario.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It explicitly discloses a non-obvious behavior: tags are created if they don't exist. However, it does not mention idempotency, effects on existing tag assignments, or error behavior, leaving notable gaps.

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 exactly two sentences, front-loading the primary action and adding one valuable behavioral note. There is no filler or redundancy—every word contributes.

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 the core action and key behavior, and the schema provides detailed parameter definitions. However, with no output schema, return values are not described, and the tool's relationship to namespaces/branches is only implied. It is adequate but has clear gaps for a mutation tool.

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 defines each parameter's meaning. The description adds no parameter-specific details beyond what is in the schema; the auto-create behavior is tool-level, not parameter-level. A 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 identifies the action ('Add') and the resource ('tags to translation keys'), making its purpose unmistakable. The additional clause about creating missing tags adds a useful distinction, confirming it handles both tagging and tag 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?

The description implies usage by naming the operation, but it does not explicitly state when to prefer this tool over alternatives like create_keys or list_tags. There is no mention of prerequisites, such as whether keys must already exist 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the tool 'updates' an existing key, implying mutation, but does not disclose whether the operation overwrites existing values, requires specific permissions, or what the response contains. For a mutation tool, this is a significant transparency 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 a single sentence that is front-loaded with the verb and resource, and clearly lists the scope of changes. Every word earns its place, with no wasted or redundant phrasing. It is appropriately sized for the tool's simplicity.

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 has 7 parameters, no output schema, and no annotations, the description is too sparse to be considered complete. It does not explain update semantics (e.g., whether all fields are overwritten), potential error conditions, or return values. The schema covers parameters but not behavioral or response context, leaving significant gaps for an agent.

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 all 7 parameters having descriptive comments. The description adds no additional parameter semantics beyond listing the updatable fields (name, namespace, description), which the schema already covers. The baseline of 3 applies since the schema does the heavy lifting.

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 ('Update') and resource ('existing translation key'), and lists the exact attributes that can be updated (name, namespace, description). This clearly differentiates it from sibling tools like create_keys or delete_keys. The purpose is unambiguous and immediately understandable.

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 used when you need to modify a translation key's name, namespace, or description, providing clear context. However, it does not explicitly state when not to use it or mention alternatives such as set_translation for updating translation values. No exclusions or alternative guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.