globalize.now

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

Beyond the annotations, the description discloses important behavioral traits: entries are upserted on a composite key, re-adding updates targetTerm and doNotTranslate flag, doNotTranslate forces targetTerm to equal sourceTerm, and matching translation-memory entries are marked stale. This is rich, relevant context that helps the agent predict 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 dense and front-loaded with the action, and every sentence adds useful information. It is somewhat long, but the length is justified by the upsert semantics, doNotTranslate behavior, and side-effect disclosure.

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 complexity, the description covers prerequisites, parameter relationships, side effects, and even output-style guidance for referring to projects/languages. An output schema exists, so return-value details are not needed in the description. 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 the baseline is 3. The description adds meaning beyond the schema by explaining the array-of-rows model, that one source term can have different targets per language, and the upsert key (project, sourceTerm, source, target). This meaningfully supplements the individual field definitions.

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

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

The description opens with a specific verb and resource: 'Add (or update) glossary entries for a project in one call.' It clearly distinguishes this tool from siblings like list_glossary and delete_glossary_entry, and the 'one call' batch aspect is highlighted.

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 a clear prerequisite: resolve language ids first with get_project. It also states the upsert behavior and when doNotTranslate should be used. It does not explicitly name alternatives or exclusions, but the sibling context makes the intended use obvious.

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 that the operation is not read-only and not destructive, so the description does not need to restate that. The description adds some behavioral context ('add as a new target language') but does not disclose details like idempotency or failure behavior; this is acceptable for a simple mutation.

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 compact and front-loaded with the core action, then adds the workflow prerequisite and a clear user-facing rule. Every sentence earns its place with no redundant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has only two required parameters, both fully documented in the schema, and an output schema exists. The description supplies the prerequisite workflow and display convention, so an agent has everything needed to call the tool 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?

The schema covers both parameters at 100%, so the baseline is 3. The description adds extra practical semantics by instructing the agent to resolve languageId through list_languages first and by establishing the convention that UUIDs are for tool calls only and never shown to the user.

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

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

The description states a specific verb ('Add'), the exact resource ('a catalog language as a new target language'), and the target ('an existing project'). It clearly distinguishes the operation from siblings like remove_project_language and 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 explicitly tells the agent to resolve the catalog language id first with list_languages, which is a concrete prerequisite. It does not spell out when to avoid this tool in favor of a sibling, but the context is otherwise 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 it as a non-read-only, non-destructive, open-world write, and the description adds real side-effect context beyond them: 'Registers webhooks and runs best-effort namespace discovery.' That 'best-effort' qualifier usefully signals the discovery may not fully succeed. It omits auth/permission details and whether re-connecting an existing repo is idempotent.

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 tight sentences, front-loaded with the core action, then the prerequisite, then side effects. Every sentence earns its place with 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 complex 9-param write operation, it covers purpose, the GitHub prerequisite, and side effects, and an output schema exists so return values needn't be described. It is slightly thin on the import-mode/scope and branch-selection semantics, which the schema handles only partially.

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 only 56% across 9 params, so the description must compensate more than it does. It clarifies the patterns param ('optionally with locale path patterns') and the GitHub installation id source, but leaves branches, provider, importMode, importScope, and gitlabConnectionId behavior unexplained beyond the schema itself.

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 ('Connect a Git repository to a project') and scopes it ('optionally with locale path patterns'). This is clearly distinguishable from siblings like detect_repository or set_repository_patterns, which do different things to an already-connected repo.

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 concrete routing hint: 'For GitHub, pass the githubInstallationId from list_github_installations', pointing to the sibling that supplies a required identifier. It provides clear context but stops short of explicit when/when-not guidance or naming alternatives (e.g., detect_repository first).

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 the write/creation safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real behavioral value beyond them: an output-presentation policy (show name and locale, never expose UUIDs) and the language-role semantics. It does not cover failure modes for invalid or duplicate language ids.

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?

Purpose is front-loaded in the first clause, followed by prerequisite, parameter semantics, and the user-facing naming rule. Every sentence carries information, though the final display-formatting sentence is slightly tangential to the invocation task itself.

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?

An output schema exists so return values need no explanation, schema coverage is full, and annotations carry the safety profile. The description covers prerequisite, language semantics, and display policy; only edge-case behavior (invalid ids, duplicates) is left unstated, which is a minor gap for a 3-parameter 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 coverage is 100%, so baseline is 3, but the description goes further by explaining the meaning of sourceLanguage versus targetLanguages ('what your content is authored in' vs 'what it will be translated into'), which is semantic context the schema does not carry. It does not clarify whether ordering or duplicates in targetLanguages matter.

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 ('Create a localisation project from catalog languages') and goes on to define the source/target language roles, which an agent cannot infer from the name alone. It is clearly differentiated from siblings like add_project_language, get_project, and list_projects.

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 an explicit prerequisite and names the sibling that satisfies it ('Resolve language ids first with list_languages'), which is genuinely actionable routing. It stops short of stating when not to use this tool or contrasting it with add_project_language for existing projects.

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 destructiveHint annotation, the description discloses a meaningful side effect: matching translation-memory entries are marked stale so affected content is re-translated without the removed term. This gives the agent important context about the downstream consequences of deletion.

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 three sentences with no fluff: the core action is front-loaded, the side effect is stated next, and the user-facing id policy is a practical addition. Every sentence 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 two-parameter destructive tool with an output schema, the description covers the essential operational context: what is deleted, where it comes from, what side effects occur, and how to communicate about it. 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?

The input schema already fully documents both parameters, including the UUID format and the note that entryId comes from list_glossary. The description reinforces this by mentioning 'by its id (from list_glossary)' but adds no new parameter-level semantics beyond what the schema provides.

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

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

The description states a specific action (delete) and resource (a single glossary entry), further scoped by 'by its id (from list_glossary)' and 'from a project in your organisation'. This clearly distinguishes it from siblings like list_glossary and add_glossary_entries.

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 explains the prerequisite that the entry id comes from list_glossary and that deletion happens within a project in the organisation. It also includes concrete guidance about using names/locales instead of UUIDs when replying to the user, though it does not explicitly contrast this tool with same-family alternatives like delete_style_guide.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds scope ('one target language') and the ID-source context, but does not disclose additional behavioral details like irreversibility or consequences beyond the annotation.

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

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

Two sentences, no filler, with the key action and key source front-loaded. The user-facing naming instruction earns its place and is compact.

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 2-parameter destructive tool with an output schema and annotations covering destructive behavior, the description covers what is needed: what is deleted, how to key it, and how to talk about the result. No meaningful gap remains.

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 value by explaining that projectLanguageId comes from get_project or list_style_guides and by providing a naming convention for user-facing replies, which helps the agent use the parameters correctly.

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 ('Delete') plus resource ('style guide'), scoped to 'one target language of a project' and keyed by project_language id. This clearly differentiates it from delete_glossary_entry and set_style_guide without needing to open the 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 provides useful prerequisites by pointing to get_project or list_style_guides for the ID, but it never explicitly says when to choose this tool over alternatives such as set_style_guide, and it gives no exclusions or when-not-to-use guidance. The intended use is implied by the title 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 already flag destructiveHint=true, and the description adds substantial context beyond them: atomicity of the batch, the 200 cap, per-id not-found behavior, cross-project blast radius on shared memories, and the repository-import caveat that deleted entries can reappear. This is exactly the extra behavioral detail 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 core action and scope before the caveats, and each sentence carries information. It is on the long side, and the trailing instruction about formatting names/locales in replies is useful but slightly tangential to tool selection.

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, cross-project-affecting tool, the description covers scope, atomicity, failure behavior, side effects, and the interaction with repository imports. With an output schema present it need not explain return shape, yet it still tells the agent the result lists affected projects.

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%: the schema already documents 'project' (UUID or slug) and 'entryIds' (1–200, from search_translation_memory). The description restates the id source and the limit but adds no syntax or format meaning beyond the schema, 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 ('Delete ... entries ... from the translation memory attached to a project') with scope ('up to 200 entries, by id') and explicitly differentiates from the sibling that produces the ids ('from search_translation_memory'). An agent can distinguish it from delete_glossary_entry and other delete 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?

Gives an explicit purpose ('remove faulty translations so future jobs stop reusing them'), the source of valid ids, and a concrete when-not/edge case (ids matching nothing are reported as not found and nothing is deleted). It also warns that the operation affects every project sharing the memory, which directly shapes whether/when to call 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that scanning targets a repository and that the output is meant to drive downstream configuration, but says nothing about rate limits, scan duration, private-repo permission requirements, or failure modes on inaccessible branches.

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 action and its outputs, then usage and prerequisite. No filler or restatement 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?

An output schema exists, so return values need not be described. Given a read-only, open-world scan tool, the description covers purpose, prerequisite, and downstream consumption adequately for an agent to call 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 coverage is 50%, so the description is expected to compensate for the undocumented parameters. It does add that installationId must be the numeric id from list_github_installations, which is genuinely useful, but owner/repo and branch semantics are left entirely to the schema, so the gap is only partially filled.

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 (scan) and resource (GitHub repository) plus the exact outputs detected: framework, locale path patterns, languages, file format. It also names the sibling tools the result feeds (create_project, set_repository_patterns), so an agent can place it in the workflow without reading other definitions.

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?

Explicitly says when to use the result (to inform create_project and set_repository_patterns) and where the required installationId comes from (list_github_installations, numeric id). This is actionable routing guidance, not just implied context.

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=false, so safety is covered. The description adds behavior beyond them: which related entities are hydrated in the response and an explicit rule that UUIDs must never be surfaced to the user, which is real operational guidance an agent would otherwise get wrong.

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, both earning their place, with the core verb and resource front-loaded. The second sentence is a non-obvious output rule rather than filler, though it is long enough that the lookup purpose briefly gets buried.

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?

An output schema exists, so return values need not be explained further, and the description still usefully names the included sub-resources. The only gap is the absence of any routing signal versus the sibling list/set tools for what is otherwise a simple one-parameter reader.

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

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

Schema description coverage is 100% and the single parameter already documents 'Project id (UUID) or slug'. The description repeats the id-or-slug acceptance without adding format or resolution details, 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 ('Get a single project by its id or slug') and adds what the response contains (languages, connected repository). It does not differentiate itself from the sibling list_projects or set_project_context, so an agent must infer the singular-vs-list distinction from the name alone.

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 a lookup flow (you must already have an id or slug) but never states when to use this tool instead of list_projects, nor any prerequisite for obtaining the identifier. It does add a reply-formatting rule, but that is output presentation guidance, not usage 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context the annotations don't carry: the payload is free-text instructions, and the second sentence constrains how identifiers may be surfaced to the user (names/locales, never UUIDs).

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 core fetch behavior; the second sentence is output-display policy that earns its place because it prevents a user-facing mistake. Slightly long but 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?

An output schema exists, so the description needn't explain return shape, and it correctly focuses on scope, id sourcing, and display rules. For a simple two-parameter read tool with full annotation and schema coverage, this is essentially complete, with only minor room for explicit sibling disambiguation.

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 goes beyond the schema by naming the provenance of projectLanguageId (get_project or list_style_guides) and by clarifying the target-language scope, adding real semantic value over the raw property descriptions.

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

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

States a specific verb (Get) and resource (style guide), and narrows scope to 'one target language of a project' with the returned content ('full free-text translation instructions'). This is clearly distinguishable from sibling list_style_guides and set_style_guide without opening any 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 tells the agent where the required projectLanguageId comes from (get_project or list_style_guides), which is practical routing guidance for invocation. It stops short of an explicit when-to-use-this-vs-list_style_guides statement or any exclusion, so it lands just below the top band.

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 and destructiveHint=false, and the description aligns perfectly. It adds rich behavioral context: while running returns status/progress without content, completed response includes files+manifest, failed response includes failure reason. This goes well beyond annotations and prepares the agent for all response variants.

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 somewhat lengthy but every sentence earns its place: purpose, behavior, response types, filtering. It is front-loaded with the main action and progressively adds detail. No fluff, but it could be tightened slightly without losing value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (polling, async job states), the description is remarkably complete. It explains the full lifecycle, what to expect at each status, the manifest, and the filtering option. Combined with the output schema (present), an agent has everything needed to invoke and interpret results 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 covers both parameters at 100%, so baseline is 3. The description adds value by explaining why targetLanguages is useful ('bound the payload of a large job') and by reinforcing that jobId comes from translate_files. It doesn't introduce new syntax but clarifies intent.

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 ('poll', 'pull back'), a clear resource (translation job started by translate_files), and differentiates from sibling translate_files by describing the retrieval/polling role. The agent immediately understands what this tool does and how it fits into the workflow.

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?

Explicitly says when to use it (after translate_files starts a job) and describes the polling loop ('call again until status is completed'). It also mentions the optional filter to bound payload, giving clear guidance on when that parameter is useful. No ambiguity about alternatives.

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 and destructiveHint as safe, so the description does not need to repeat that. It adds the organisational scope ('available to your organisation'), which is useful but minimal. No deeper behavioral detail (e.g., authentication requirements, installation state filtering) is disclosed, but given the annotations cover the safety profile, a 3 is appropriate.

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

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

Two sentences, no fluff. The first sentence states the core purpose; the second describes output consumption. All information is front-loaded and 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?

An output schema exists, so return-value documentation is not needed. The description covers the essential usage: listing installations and linking to dependent tools. It does not mention potential prerequisites (e.g., prior setup via start_github_install) but that is a minor gap for a simple list operation with no parameters.

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 are zero parameters, so the 0-parameter baseline of 4 applies. The description adds nothing about parameters because there are none, and the schema obviously has 100% coverage. This is a trivial but correct score.

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

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

The description clearly states the action ('List') and the target resource ('GitHub App installations'), scoped to 'your organisation'. It also directly names the sibling tools that consume the returned installationId, which differentiates it from other list tools like list_projects or list_glossary.

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 explicitly tells the agent what to do with the output (use the installationId with list_repository_branches, detect_repository, and connect_repository), giving actionable guidance. It does not explicitly mention when not to use it or a direct alternative, but the connection to these siblings makes the usage context reasonably 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 and destructiveHint=false. The description adds useful behavioral context by describing pagination behavior and the instruction to present id-based results using names/locales to the user, which goes beyond the structured annotations without contradicting them.

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

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

The description is compact and front-loaded: it states the core purpose first, then filter/pagination behavior, then the user-facing presentation rule. Every sentence earns its place without redundant 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 read-only list tool with a full output schema, 100% parameter documentation, and safety annotations, the description covers the essential operational details: pagination, optional filters, and the presentation convention for ids. Nothing critical is missing for correct invocation.

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 filtering by source/target project_language id and pagination cursor, but these largely restate what the input schema already explains rather than adding significant 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 and resource: 'List the glossary entries for a project'. It also clarifies what an entry is ('a source→target term pair with its languages and id'), which clearly distinguishes it from sibling tools like add_glossary_entries or delete_glossary_entry.

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 concrete usage guidance: optional source/target filtering, pagination via cursor, and a user-facing naming convention for projects/languages. It does not explicitly contrast with alternatives or state when not to use the tool, but the context is clear and actionable.

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 the read-only, non-destructive nature of the tool. The description adds valuable behavior beyond that: it is a global catalog, search matches name or locale, and returned ids are for tool calls only. This gives the agent practical behavioral context without contradicting annotations.

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

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

The description is compact and front-loaded: it states the core purpose first, then filtering, then return value usage and a user-facing formatting rule. Every sentence adds actionable information with 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 simple optional-parameter read tool with an output schema and safety annotations already provided, this description is complete. It covers the catalog scope, filtering behavior, what information is returned and why it matters, and how to format language references for the user.

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 only defines 'search' as a string with no explanation. The description fully compensates by explaining the optionality and exact matching semantics: it filters by language name or locale. This is the essential meaning an agent needs to use the parameter correctly.

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 ('List'), a clear resource ('the global Globalize language catalog'), and an optional filtering behavior. It is readily distinguishable from sibling list tools like list_glossary and list_projects.

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 explains when this tool is needed: it returns the id and locale required to create a project or add a project language. It also gives display guidance for referring to languages. It does not explicitly list when not to use it or name alternatives, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world scope, so safety is covered. The description adds value beyond that with the exact shape of the returned summary and the rule that UUIDs are for tool calls only. It does not mention pagination or result-set limits for an organisation-wide listing, which is the remaining 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?

Front-loaded with the action and return fields, then the sibling distinction, then the id-vs-name convention. The third sentence is slightly tangential to tool invocation but still earns its place by preventing UUID leakage in user replies.

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?

An output schema exists so return-value documentation is not required, yet the description still summarises it usefully. Combined with the sibling contrast and the presentation convention, it is complete enough for a zero-parameter read tool; only pagination/scale behaviour is unaddressed.

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?

Zero parameters, so the baseline of 4 applies. There is nothing in the schema for the description to clarify or contradict, and no missing parameter documentation to compensate for.

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 all projects in your organisation") and enumerates the returned fields (id, slug, name, plus source/target language id/name/locale). It distinguishes itself from the closest sibling by noting get_project returns the full project.

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

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

Explicitly routes the agent: use this for the list, use get_project when the full project is needed. It also gives an output convention for the user-facing reply (use name and locale, never ids), which is actionable guidance rather than 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 declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral value beyond the annotations: a 1,000-branch truncation cap, alphabetical ordering, and the notable rule that the default branch is included (flagged) even when it sorts past the cap.

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 tight sentences with zero filler. Scope and required input source are front-loaded, and the pagination/ordering caveat follows as the second priority.

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?

An output schema exists, so return-value documentation is not needed, and the description still usefully explains ordering and truncation behavior. The only gap is that two of three parameters (owner, repo) are undocumented anywhere, which is minor given their conventional meaning in a GitHub-scoped API.

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 33% – only installationId carries a schema description ('GitHub App installation id'), while owner and repo have none. The description reinforces that installationId must be numeric and come from list_github_installations, partially compensating, but owner/repo semantics (owner/repo slugs) are left entirely implicit. 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+resource ('List the branches of a GitHub repository') plus its scoping qualifier ('accessible to an installation'), which distinguishes it from sibling tools like list_github_installations and connect_repository. An agent can identify exactly what this returns without opening the 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?

Provides a clear prerequisite and cross-reference: 'Use the numeric installationId from list_github_installations,' which routes the agent to the correct sibling for the required identifier. It lacks explicit when-not-to-use guidance, but for an unambiguous list operation there is little ambiguity to resolve.

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 and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: what the response contains, what it deliberately omits, and a UX rule about presenting names/locales instead of UUIDs.

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 core listing behavior, then the return-scope caveat, then the presentation rule. Every sentence carries information, though the UUID-display rule is a presentation convention rather than tool behavior and slightly dilutes focus.

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?

An output schema exists, so return values need no explanation, yet the description usefully summarizes the shape anyway. Combined with full schema coverage and read-only annotations, an agent has everything needed to call 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 coverage is 100% and the single 'project' parameter is fully documented in the schema as id or slug. The description adds nothing about the parameter itself, 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?

States a specific verb and resource ('List the per-language style guides for a project') and immediately scopes the payload: which languages have one, the guide id, and the instruction length. It is clearly distinguishable from get_style_guide, which it names.

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?

Explicitly routes the agent: this tool returns metadata only because 'the instructions themselves are not included', and get_style_guide returns one language's full text. That is a named alternative plus the condition that selects 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?

Annotations already supply destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it reinforces that this removes a project-language association, explains where the correct ID comes from, and instructs the agent to use name/locale rather than UUIDs when communicating with the user.

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 compact and front-loaded: the primary action is stated first, followed by the key parameter provenance warning, then the user-facing display rule. No sentence is filler; each 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 two-parameter destructive tool with an output schema and annotations already in place, the description provides everything needed: the action, the correct ID source, the wrong ID pitfall, and user-facing formatting guidance. Nothing critical is missing.

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

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

The schema already documents both parameters at 100% coverage, which sets a baseline of 3. The description adds significant meaning to projectLanguageId by specifying that it must come from the targetLanguages list returned by get_project and must not be a catalog language id, going beyond the schema's minimal wording.

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 and resource: 'Remove a target language from a project.' It also clarifies the object being removed is a project_language, not a catalog language, which distinguishes this tool from other deletion/removal tools among the siblings.

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 context for correct use by specifying that the caller must pass the project_language id from the targetLanguages list returned by get_project, and explicitly warns against using a catalog language id. It does not explicitly name alternatives or exclusions, but the guidance is strong enough for an agent to select and call this tool correctly.

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 readOnlyHint/openWorldHint/destructiveHint annotations, it discloses pagination behavior (cursor chaining), the return shape, and a significant cross-project semantic: the memory may be shared and deleting an entry removes it for every attached project. It also warns that ids are for tool calls only and must not be shown to users – non-obvious operational context that 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 core purpose and filtering are front-loaded in the first two sentences and are efficient. The final sentence about presenting names/locales rather than ids is useful but reads as a tangential user-facing convention rather than tool-selection guidance, slightly diluting focus.

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 an output schema present, the description need not detail return values, yet it summarises them briefly and covers pagination, shared-memory scope, and the delete follow-up. Nothing an agent needs to invoke this safely 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% and the schema already documents q as case-insensitive substring, locale matching behaviour, and defaults. The description broadly restates the filter semantics ('case-insensitive substring of the source or translated text, and/or by source and target locale') without adding new syntax or edge-case guidance, 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?

The description states a specific verb and resource (search the project's translation memory), defines what the memory actually is (stored source→translation pairs reused by future jobs), and names the sibling tool it feeds into (delete_translation_memory_entries). An agent can distinguish it from list_glossary or list_style_guides 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?

It gives an explicit use case (find faulty entries, then pass ids to delete_translation_memory_entries), names the alternative tool, and states filtering options. Routing and intent are unambiguous.

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 destructiveHint=true and readOnlyHint=false, so the agent knows this mutates state. The description hints at overwrite by telling the agent to read the current value first and caps input at 1000 characters, but it never says out loud that the existing context is replaced wholesale rather than merged or appended — the single most important behavioral fact for 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 purpose and constraints are front-loaded and efficient, but the final sentence about how to name projects and locales in replies is a server-wide formatting convention rather than tool-specific information and dilutes a description that should focus on this call. Slightly over-sized for a two-parameter setter.

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?

An output schema exists, so return values need no explanation, and the character limit plus read-before-write pointer are present. What is missing is the overwrite/merge semantics of a destructive write — the one thing an agent cannot infer from the schema or annotations alone.

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 meaning the schema lacks: it explains what the 'context' string should contain (product description, audience, tone) and clarifies via the UUID/locale note that the 'project' value is an identifier used only in tool calls, never shown to users.

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 ('Set a project's project-wide context') and immediately defines what that context is (free-text prompt guidance shared across every target language — product, audience, tone). This clearly separates it from siblings like set_style_guide and set_repository_patterns, which set other artifact types.

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 read-before-write workflow by naming get_project as the way to inspect the current value, and states the scope constraint (shared across all target languages) and the 1000-character limit. It does not explicitly say when to prefer this over set_style_guide, so it falls 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 indicate readOnlyHint=false, so mutation is expected. The description adds valuable behavioral detail: existing identical patterns are skipped (non-destructive to duplicates) and each pattern must contain exactly one {locale} and at most one {namespace}. This goes beyond what annotations provide without contradiction.

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

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

Two tightly written sentences with zero filler. The primary action and target are front-loaded, and the constraint on pattern content is presented efficiently. Every sentence 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?

Given an output schema exists and the parameter schema is detailed, the description covers the core action and key constraint but omits details like behavior on invalid input, handling of partial failures, or how patterns interact with existing ones (beyond skipping duplicates). For a tool with two parameters and moderate complexity, this is adequate but not 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?

Schema description coverage is 0%, so the description carries full responsibility for parameter meaning. It clarifies the expected format of the 'pattern' field (placeholders for locale and namespace) but does not explain 'repositoryId', 'fileFormat', or 'options'. This partial compensation earns a middle score.

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

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

Description uses specific verb 'Add' with a concrete resource 'locale path patterns' and identifies the target as 'connected repository'. This clearly differentiates from siblings like connect_repository or set_project_context, making the tool's 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 states the action is additive ('Add locale path patterns') and implies it applies to an already-connected repository, providing contextual usage. It doesn't explicitly contrast with alternatives or mention when not to use it, but the context is clear enough for an agent to select it over similar tools.

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?

The description meaningfully expands on the annotations by disclosing that a brand-new guide always marks translation memory stale, while updates only do so if recheckExistingTranslations is enabled. It also adds important interaction guidance about never showing UUIDs to the user, which is beyond the structured annotations. No contradiction with destructiveHint=true is present.

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 tightly structured: first sentence states the action and scope, second explains the critical side-effect behavior, third gives user-facing formatting rules. Every sentence carries essential information with no filler or repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 4-param schema, 100% schema coverage, output schema presence, and annotations, the description covers everything needed to invoke the tool correctly. It explains how to identify the target language, what side effects to expect, how to handle updates, and even how to refer to results in user-facing replies.

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, but the description adds useful semantics beyond the schema: it clarifies that projectLanguageId comes from get_project, that instructions are drafted by the agent, and that the new-vs-update distinction changes the meaning of recheckExistingTranslations. This is more than the bare schema definitions provide.

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 ('Create or replace the style guide') with a clear resource scope ('for one target language of a project') and the key identifier (`project_language id`). It distinguishes this tool from siblings like list_style_guides or delete_style_guide by defining exactly what this operation does.

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 context on when to create vs replace, and explains when recheckExistingTranslations should be set for an update. It does not explicitly name alternative sibling tools such as list_style_guides or add_glossary_entries, but the create/replace framing and side-effect guidance make the intended use case apparent.

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 annotations, the description explains the interaction model: it returns a URL that must be shown to the user for browser-based installation confirmation, and the installation id is obtained later via a follow-up call. This adds useful behavioral context about the asynchronous, user-mediated nature of the 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?

Three compact sentences front-load the purpose, describe the returned value, and give the next step. Every sentence earns its place with no filler 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 0-parameter tool with an output schema and clear annotations, the description covers the full flow: what happens, what to do with the result, and what to call next. Nothing needed 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?

The tool has zero parameters, so the schema already tells an agent everything needed about inputs. The description reinforces the 'returned URL' outcome but does not need to explain parameter behavior. A baseline of 4 is appropriate for 0-parameter tools.

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 clear action ('Begin connecting GitHub') and specifies the concrete deliverable: an install URL for the Globalize GitHub App. It distinguishes itself from the sibling list_github_installations by framing this as the initial setup step that precedes retrieving the installation id.

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 workflow: call this to start connecting GitHub, surface the returned URL, wait for user confirmation, then call list_github_installations. It does not explicitly state when not to use it, but the sequence is implied strongly enough for a simple 0-parameter tool.

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 annotations only indicating readOnlyHint=false and openWorldHint=true, the description carries the behavioral burden and does so excellently. It discloses that translation runs asynchronously, that the call returns immediately with { jobId, status }, and that the agent must poll get_translation until a terminal status. This is genuinely valuable beyond what annotations provide.

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 longer than average, but nearly every sentence earns its place: the supported formats list is dense, the default behavior is explicit, and the async polling instructions are essential. The key facts are front-loaded and the follow-up flow is clearly separated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists and three well-documented parameters, the description is complete: it covers input formats, parameter defaults, return shape, asynchronous behavior, and the full follow-up flow via get_translation. An agent has everything needed to invoke the tool and interpret what happens next.

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 meaningful call semantics beyond the schema, especially the note that files are parsed by content rather than name, so the literal file content should be passed as-is. It also clarifies the targetLanguages parameter as a subset that defaults to all project targets.

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 opens with a specific verb and resource: 'Submit one or more source files to be translated as a single job.' It clearly distinguishes the submission action from the polling tool get_translation, and the detailed format list removes ambiguity about what kinds of files are accepted.

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 context on how to use the tool: pass files as-is, target languages default to project targets, and results are fetched via get_translation. It does not explicitly state exclusions or alternative tools, but the async workflow is spelled out well enough that an agent knows exactly when and how to follow up.

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