Localazy MCP by usefulapi

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=true), so the description's added context is valuable: it discloses the Reviewer role requirement, the 1,000-term project cap, the underlying endpoint, and that the term takes effect for translators and Localazy AI going forward.

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 four short sentences with the write operation front-loaded. Every sentence carries useful information (action, quota, role, effect, endpoint) with no filler or repetition.

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 create tool with full schema coverage and existing annotations, the description supplies the key prerequisites and limits an agent needs. It does not cover duplicate-term behavior or what a successful response contains, which is a minor gap given there is no 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?

Schema description coverage is 100%, so all six parameters are already documented in the schema, making 3 the baseline. The description adds no parameter-level detail beyond the schema and its phrase 'one term' does not convey the per-language array structure documented in 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 gives a specific verb and resource: 'add one term to a project's glossary', and scopes it with a per-project limit. It is clear on its own, but it never explicitly distinguishes itself from the sibling `localazy_update_glossary_term` or states what makes creation different from updating.

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?

Usage is implied by the 'WRITE: add one term' framing and the prerequisite that it needs the Reviewer role, but there is no explicit when-to-use guidance versus alternatives, no when-not-to-use, and no routing to `localazy_update_glossary_term` or `localazy_list_glossary`.

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?

Beyond the readOnly/destructive/openWorld annotations, it discloses a quota constraint ('Counts against the project's daily fetch cap'), pagination mechanics ('Pages of up to 1000 keys'), and the return shape including plural objects. These are behavioral facts the annotations do not carry, so it adds genuine value.

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?

Front-loads the core purpose, then layers paging, flags, quota, and the endpoint. Every clause carries information, though the trailing raw endpoint path is slightly redundant with the purpose statement. Dense but well-ordered.

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 output schema, the description correctly compensates by describing return values (key id, key path, translation as string/array/plural object) and covers pagination and quota for a 9-parameter tool. It omits error behavior, but for a read-only listing call it is essentially 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 the schema already documents every parameter and the baseline is 3. The description adds meaning by explaining how `next` chains pages, the 1000-key page ceiling, and the semantics of extra_info/no_content in relation to the returned data, lifting it above 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?

States a specific verb+resource+scope: 'Read the strings of one file in one language', and enumerates the returned fields (key id, key path, translation shape). This clearly separates it from siblings like localazy_list_files or localazy_list_key_links, which cover different resources.

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?

Gives concrete usage context for the paging and flag parameters ('pass `next` for the following page', 'Set extra_info for hidden/limit/deprecated/comment', 'no_content to list keys without text'). It does not name a competing sibling or state when NOT to use this tool, so it falls short of explicit alternative routing.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the underlying REST endpoint, which is minor context and reveals nothing about errors, auth scope, or return shape beyond what annotations imply.

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 fragments, purpose front-loaded before the endpoint. The REST path is somewhat redundant for an agent-facing tool but runs to only a few 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?

A simple single-resource read with full schema coverage and annotations covering safety; no output schema exists so return-value explanation is not required. Adequate, though it could note what happens if the term id is not found.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented with their source tools. The description adds no additional meaning beyond the schema, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: retrieves a single glossary term by id. The 'one ... by id' phrasing implicitly distinguishes it from the sibling localazy_list_glossary, though no sibling is named explicitly.

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 versus localazy_list_glossary or localazy_get_glossary_term's related update/create tools. The precondition that ids come from list tools exists only in the schema, not the description.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the endpoint is undocumented and the reply is returned verbatim as Localazy sends it, warning the agent not to expect a normalized shape. It does not mention polling cadence or batch lifecycle states.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences: what it returns, the required link to localazy_import_keys, then the undocumented-endpoint caveat and raw path. Front-loaded and free of 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?

With no output schema, the description importantly discloses that the response is an unprocessed passthrough from an undocumented endpoint, which is exactly the caveat an agent needs to avoid over-parsing results. Minor gaps remain around progress states or whether polling is expected, but the essential context is present.

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% and both parameters already carry descriptions in the schema ('project id or slug from localazy_list_projects', 'the `import_batch` returned by localazy_import_keys'). The description restates the import_batch provenance rather than adding new syntax, format, or constraint detail, so it sits at 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?

States a specific verb+resource ('Progress of an import batch') and explicitly ties it to the sibling that creates the batch, localazy_import_keys, plus the underlying endpoint GET /projects/{projectId}/import/{importBatch}. An agent can distinguish it from list/import siblings without opening a schema.

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?

Clearly specifies the precondition: this only makes sense for a batch started with localazy_import_keys, and instructs the caller to pass that call's `import_batch`. It stops short of saying what to do when no batch exists or how to poll/abandon, so it is not a full when/when-not specification.

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?

Goes well beyond the readOnly/destructive annotations: discloses billing behavior (no credit consumption), a latency caveat (first request for a key can be slower), and persistence behavior (nothing is saved). These are exactly the traits an agent needs that structured fields cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the purpose and the credit-cost distinction. The trailing raw endpoint path is mildly redundant given the structured schema but serves as confirmation, so it is nearly waste-free.

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 output schema, the description partially covers the return shape ('one per engine'), and annotations plus the description handle safety, billing, latency and persistence. It could say more about the suggestion payload format, but nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are already documented, including the target/source language defaults and where key_id and project come from. The description adds no param-level meaning beyond 'one source key into a target language', so the baseline 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?

States a specific verb+resource+scope: MT suggestions, one per engine, for a single source key into a target language. It distinguishes itself from the paid path by naming localazy_translate_with_ai, and the 'MT' qualifier separates it from the TM sibling.

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?

Gives a clear condition for choosing this tool: it's free and consumes no Localazy credits, whereas Localazy AI does, pointing to localazy_translate_with_ai as the alternative. It stops short of contrasting with localazy_get_tm_suggestions, so the MT-vs-TM choice is left to inference.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the cost model ('Free; no Localazy credits') and the fact that results carry their originating project, both of which affect whether and how an agent calls this.

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 compact sentences that front-load the purpose and return content, followed by a short cost note and the endpoint path. The raw endpoint string is mildly redundant but useful for API-literate callers; nothing else is wasted.

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 output schema, the description does the necessary work of describing the return shape (earlier translations plus their source project). For a read-only suggestion lookup with fully documented parameters, that is close to sufficient; ordering, result limits, and the effect of the optional 'from' filter are left implicit.

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 key_id, project, to, and from (including its project-default behavior) are already fully documented. The description only restates 'one source key into a target language' without adding format, default, or constraint detail, so the baseline 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?

States a specific verb+resource+scope: TM suggestions for one source key into a target language, and clarifies that these are earlier human translations of the same text. This is enough to separate it from most siblings, but it never explicitly distinguishes itself from the near-identical localazy_get_mt_suggestions (machine translation), which is the main confusion risk.

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 'Free; no Localazy credits' note implies this is a cheap operation worth trying, and the one-key/one-language scope is stated, but there is no explicit when-to-use rule and no mention of when to prefer localazy_get_mt_suggestions or localazy_translate_with_ai instead.

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?

Far exceeds the annotations: it states nothing is deleted or deprecated, that existing current translations are not overwritten by default, that identical-to-source translations are skipped, that changing source text marks translations as changed, and that calls consume a daily import cap (Free: 100/day). It also discloses the Owner-role requirement and the returned import_batch id. This is exactly the mutation/accounting context an agent needs before a destructive write.

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 WRITE label front-loads the critical classification and the sentences are dense with non-redundant facts (limits, defaults, role, quota, return value). It is on the long side for a single dense paragraph, but almost no sentence is filler, so the length is largely earned.

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?

Even without an output schema the description explains the return value (import_batch id) and the follow-up tool for tracking it, and covers auth, quota, file/language scoping, and defaulted behavior. For a 6-parameter nested-object write with a review path, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3, but the description adds real semantics: the 50-entry ceiling, the dotted 'home.title' key convention, and that the default language is the source language so omitting it changes source text rather than translations. gain over structured fields is genuine, though file_name's default (content.json) is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (add or update), resource (string keys), and tight scope (up to 50 keys, one file, one language) with the flat key->text shape spelled out. The 'WRITE:' prefix and the HTTP endpoint make it immediately distinguishable from read-only siblings like get_file_keys or get_import_progress.

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?

Gives clear when-to-use context: default language targets the source language, while passing a different language imports translations, optionally routed through review via import_as_new. It also names the Owner role prerequisite and points forward to localazy_get_import_progress. It does not explicitly compare against alternative write paths such as submit_translation or update_key_properties, so it stops short of full alternative routing.

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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them: the Manager role requirement and the endpoint, which is meaningful authorization information for a read 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 sentences that are front-loaded with the core action, followed by the permission and endpoint details. No filler and every clause carries signal.

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 no output schema, the description names what is returned (release tags and their metadata file URLs, covering languages and plural rules), plus the auth requirement and endpoint. An agent has everything needed to invoke and interpret the call.

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?

Only one parameter with 100% schema description coverage, so the schema fully documents 'project' (id or slug, with provenance from localazy_list_projects). The description adds little beyond reusing the term 'project', so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (Localazy CDN release tags, plus each tag's metadata file URL), and clarifies the payload of the metadata (languages, plural rules). No sibling tool touches CDN metadata, so it is cleanly distinguishable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides the operative prerequisite ('Needs the Manager role') and the underlying endpoint, which tells the agent the permission context required to call it. It does not name an alternative, but no sibling overlaps this capability, so there is little to disambiguate.

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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds value beyond that by disclosing the response shape (id, name, type, path) and the underlying endpoint, which is genuinely useful given there is no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, each earning its place: what it lists, where to go next, and the endpoint. The core purpose is front-loaded with zero 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 single-parameter read tool with no output schema, the description supplies the return fields and the sibling routing an agent needs to act correctly. Annotations cover the safety profile, leaving little missing, though it does not mention pagination or whether the list is exhaustive.

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?

Only one parameter, and schema description coverage is 100% – the schema already explains that 'project' is a Localazy project id or slug sourced from localazy_list_projects. The description adds no syntax or format detail beyond that, so the baseline 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?

States a specific verb and resource ('List the files in a project') and enumerates the returned fields (id, name, type, optional path), so the agent knows exactly what comes back. It also explicitly distinguishes itself from localazy_get_file_keys by naming that sibling and its 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 gives a clear routing rule: use a file id with localazy_get_file_keys to read strings. That tells the agent the natural next step after this call. There is no explicit when-not-to-use or exclusion, so it stops 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds the API endpoint mapping, which is mildly useful, but says nothing about pagination, result size, or auth requirements for a collection-returning call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence naming the scope and the fields returned, followed by the endpoint as a compact appendix. No filler, no repetition of the title.

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 output schema, the description usefully compensates by enumerating the returned fields and the endpoint, and the single required parameter is fully documented in the schema. It stops short of stating whether the result set is paginated or bounded, which is the only real gap for a list 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?

There is a single parameter with 100% schema description coverage — the schema already tells the agent it is a project id or slug from localazy_list_projects. The description adds no parameter detail beyond scope ('of a project'), so the baseline 3 for schema-driven parameters 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 states the resource precisely ('All glossary terms of a project') and enumerates the returned fields (id, description, translate/case-sensitive/exact-match flags, term per language), plus the underlying endpoint. The word 'All' plus the plural resource implicitly distinguishes it from the singular siblings get_glossary_term and update_glossary_term.

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?

Usage is only implied by the tool's nature — an agent can infer 'use this to see the glossary' — but no when-to-use condition, prerequisites, or named alternative (e.g. get_glossary_term for a single term) is given. Adequate but with clear gaps.

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?

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so safety is covered. The description adds real value by describing the shape of the result (type id, name, plural/array/structured-key support) and the endpoint, which matters since there is no output schema.

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 tight sentences: contents first, the practical tie-in to localazy_import_keys second. Every clause carries information, with no padding.

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 parameterless read-only list with no output schema, the description compensates by enumerating the returned fields and linking to the consuming tool. Nothing an agent needs to call it correctly is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there are no parameter semantics to document; the baseline for a no-param tool is 4. Nothing extra is needed or missing here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (import file types Localazy can store strings as) and enumerates the returned fields, making it clearly distinct from other list_* siblings. No other tool covers import formats.

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 ties itself to a concrete use case by noting 'The `json` type is what localazy_import_keys uses,' which tells the agent when this matters. It stops short of stating explicit when-not or alternative tools, but the routing intent to localazy_import_keys 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that: an explicit authorization requirement (Reviewer role) and a paginated/cursor-based access pattern, plus the underlying endpoint. It does not state rate limits or pagination termination beyond what the schema says.

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 compact sentences, front-loaded with the resource and its returned fields, followed by the prerequisite and endpoint. Every clause carries information the agent needs to decide and call correctly; nothing is padded.

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?

Although there is no output schema, the description compensates by naming the returned fields (key id, linked project id, linked key id) and that results are paged. Combined with the Reviewer-role prerequisite and the read-only annotations, an agent has everything needed to invoke this 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?

Schema description coverage is 100%, so all three parameters (project, limit, next) are fully documented in the schema itself, including the paging chain semantics. The description only says 'paged' and does not add format or constraint detail beyond the schema; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — list links between duplicate source keys — and goes further by enumerating the fields each link carries (key id, linked project id, linked key id), so the agent knows exactly what a 'link' is. No sibling tool in the list touches key links, so it is unambiguously differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides one real prerequisite — 'Needs the Reviewer role' — and flags paging, which is useful selection context. However it names no alternative tool and gives no when-to-use/when-not guidance, so the agent must infer that this is the way to audit duplicate-key links.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context: token-based visibility scoping ('a project token reaches one project') and the exact extra data the optional flags return. It does not mention pagination or response size 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?

Two sentences that are front-loaded with the core action, and the parenthetical token-scoping caveat is placed where it matters. Dense but every clause carries information; the field enumeration is slightly list-heavy but 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?

With no output schema, the description correctly compensates by enumerating return fields and the effect of each optional param. Complete for invocation; the only gap is absence of any note on pagination or ordering of the project 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 coverage is 100%, so baseline is 3, but the description goes beyond the terse schema text: it names the specific per-language counters (active, review, current, translated, sourceChanged, needImprovement) and spells out that 'organization' adds keys used/available plus feature flags, clarifying the cost of each flag.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('List the Localazy projects') and enumerates the returned fields (id, slug, name, source language, role, visibility). It doesn't need sibling differentiation because none of the siblings list projects, but it also never explicitly distinguishes itself from them.

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?

Explains scope ('the token can reach') and what the two optional flags add, which implies when to enable them, but gives no explicit when-to-use vs alternatives guidance or prerequisites. Adequate but implied rather than stated.

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?

Annotations declare destructiveHint=true, but the description goes well beyond them: it spells out that the write overwrites the existing translation and goes live in the next download/CDN release, that a translator's value is only a candidate, that no placeholder/plural/length validation runs, that the source language cannot be written, and that the caller should inspect the reply's `stored` field. This is exactly the extra behavioral context the annotations cannot convey.

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?

Front-loaded with the operation type and scope, then layered with role semantics, validation gaps, and the endpoint. Dense but each clause carries information; the trailing raw endpoint path is the only near-filler, and the whole thing is a single efficient paragraph.

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 4-parameter write tool with no output schema, the description covers the mutation effect, who it affects, what validation is skipped, and where to look for the result (`stored`). Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic constraints on top: values are 'stored as-is, with no placeholder, plural or length check' and the source language cannot be targeted via `lang`. These are behavioral facts about the parameters that the schema alone does not state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+scope: 'set the translation of ONE source key in ONE target language'. The 'WRITE:' prefix and the single-key/single-language scoping distinguish it from siblings like localazy_translate_with_ai or localazy_import_keys without needing to open their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the role-dependent outcome clearly: reviewers/managers/owners/trusted translators write live, a plain translator's value becomes a pending candidate. That is strong context for predicting effect, but it never explicitly names an alternative tool or states when not to use this one (e.g., bulk translation via localazy_translate_with_ai).

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?

Although annotations already declare destructiveHint, openWorldHint and non-idempotency, the description adds valuable behavior beyond them: credits are consumed per translated word, nothing is persisted to the project, only returned, plus explicit 10 req/min, 32-item and 16,384-character limits and a required Owner role. This is exactly the operational context the annotations cannot convey.

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 cost warning is front-loaded in caps and each following clause carries real information (limits, storage behavior, role, endpoint). It is dense but well ordered; the repeated Beta/limits block could be tightened slightly.

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, credit-spending mutation tool with no output schema, the description covers cost, persistence, rate limits and auth prerequisites. It stops short of explaining response shape (mitigated by no output schema) or routing to alternative translation tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents project, from, to, items and fallback. The description adds only the 'up to 10 texts' framing plus request-level limits, so the baseline 3 applies. Note the stated '32 items per request' sits awkwardly against the schema's maxItems of 10.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('translate up to 10 texts with Localazy AI') and pins the operation to POST /projects/{projectId}/ai. An agent can distinguish this from sibling suggestion/candidate tools such as localazy_get_mt_suggestions without opening a schema.

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 strong constraints (credit cost, rate limit, item/char ceilings, Beta, Owner role) but never states when to prefer this over alternatives like localazy_get_mt_suggestions or localazy_submit_translation. Usage is implied by the constraints rather than routed.

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?

Annotations already flag destructiveHint=true and idempotentHint=true, and the description goes further: it explains the replace-not-merge behavior ('the term list and any flags you pass overwrite the old values'), names the required Reviewer role, and discloses the underlying PUT endpoint. This tells the agent exactly what data is lost on invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the WRITE marker and the destructive-replace warning before the role and prerequisite details. No filler or restated field documentation.

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 7-parameter mutation with no output schema, the description supplies the critical missing pieces: mutation semantics, permission requirement, read-before-write workflow, and the API surface. An agent has everything needed to invoke it 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?

Schema description coverage is 100%, so the schema carries the baseline load. The description still adds non-obvious semantics: that the term array and any flag parameters overwrite prior values rather than patching them, which changes how the agent should populate optional 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?

Opens with the operation class (WRITE) plus a concrete verb+resource: replacing the content of one glossary term. It is immediately distinguishable from localazy_create_glossary_term and localazy_get_glossary_term, which it names as the read counterpart.

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?

Gives a required precondition (Reviewer role) and a sequencing instruction (read the term first with localazy_get_glossary_term), which routes the agent to the right sibling. It does not state when to prefer this over creation or what to do when the term does not exist, so it falls short of full when/when-not 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?

Adds real context beyond the annotations: the Manager role requirement, the partial-update contract (omitted fields stay unchanged), and the explicit non-effects (no text changes, no deprecation, no deletion). The only mild tension is destructiveHint=true versus the stated non-destructiveness, but overwriting existing property values is consistent with a destructive hint.

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 dense sentences with the operation type front-loaded, followed by the mutation semantics, the permission requirement, and the exclusions. No 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 five-parameter mutation with no output schema, the description covers auth, partial-update semantics, and side-effect boundaries, which is enough for correct invocation. Return shape is unspecified, but annotations already declare idempotency and safety, so the gap is minor.

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 all five parameters are already documented, including the -1 sentinel for limit. The description paraphrases the same three mutable fields without adding format or constraint detail, so 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?

States a specific verb (change) and resource (a source key's properties), then enumerates the three mutable fields: translator comment, max translation length, hidden flag. It also names the underlying endpoint, so the agent knows exactly what operation this is.

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?

Gives clear context on when this applies (editing existing key properties, with omissions preserved) and explicit exclusions: it does not change texts and cannot deprecate or delete the key. It does not route to a specific sibling alternative, but no sibling performs the same job.

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