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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: it is a soft-delete that is restorable from the Guide admin UI, the article and all translations become invisible to end users, and it returns a confirmation message. The statement that permanent deletion is unavailable via the API is a critical behavioral disclosure.

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 destructive semantics are front-loaded in the first clause and each sentence carries useful information. There is mild redundancy with 'Guide admin UI' appearing in two separate sentences, but overall it is efficient and 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?

For a destructive mutation with no output schema, the description covers the safety profile, restore path, end-user impact, and return value. An agent has everything needed to call it correctly and safely.

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 both parameters are fully documented in the schema itself, including the confirm safety guard. The description only echoes the guard ('Guarded by a required confirm flag') without adding syntax or format detail beyond what the schema provides, 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 ('Archive (soft-delete) a Help Center article') and immediately clarifies the semantics of the operation. It distinguishes itself from the sibling update_article by naming it explicitly as the non-destructive alternative.

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 tells the agent when to use this tool versus alternatives: it is the only removal the API offers, permanent deletion is not available, and update_article with draft: true should be used to hide temporarily. This covers when-to-use, when-not, and named 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?

With annotations already covering the read-only/safe profile, the description adds substantial behavioral context: it discloses that the outdated flag is set only by Guide's native workflow and NOT by API edits, that structure mismatches warn of row misalignment, and that it performs three GET calls. This is exactly the beyond-schema context an agent needs to interpret output correctly.

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 purpose followed by five numbered signals, so structure is legible. It is dense and long, but with no output schema nearly every sentence carries necessary return-value semantics, 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?

No output schema exists, and the description fully compensates by enumerating each returned signal (Freshness, outdated flag, structure check, per-section table, word counts) and their semantics. For a read-only comparison tool, nothing an agent needs to call and interpret it 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 all three parameters are already documented with descriptions. The description consistently uses 'source' and 'target' but adds no format or constraint details beyond what the schema provides, so 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 (compare) and resource (two locales of the same article) plus the decision it supports (whether the target translation needs work). An agent can distinguish this from siblings like find_translation_gaps or list_article_translations 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?

Strong guidance on how to use the result — 'prefer Freshness' over the outdated flag, and warnings that word-count gaps must not be treated as divergence. However, it never explicitly names when to choose this tool over sibling gap-analysis tools, so the comparison framing is left implicit.

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 cover the safety profile (not read-only, not idempotent, not destructive). The description adds genuinely useful behavior beyond them: the tool returns the created article with its id, and the supplied locale becomes the article's source_locale. It does not mention the draft/publish default or any rate/permission constraints, which keeps it short of a 5.

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-loaded with the core action and return value, then the permission prerequisite, then the sibling handoff. 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 an 11-parameter creation tool with no output schema, the description covers the key gaps an agent needs: the return value, the critical required permission_group_id, and the translation follow-up path. It leaves some behavioral detail (draft default behavior, author default) to the schema, which is acceptable given full schema coverage.

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%, including usage hints like list_sections/list_labels/list_user_segments, so the schema carries parameter explanation. The description only reinforces permission_group_id and the locale↔source_locale relationship, adding marginal value over structured data.

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?

Specific verb (Create) plus resource (article in a section) and it states the return (created article with id). It is clearly distinguishable from sibling create_article_translation, which it explicitly names as the follow-up for other locales.

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 sequencing guidance: use list_permission_groups to obtain the required permission_group_id, and use create_article_translation afterwards for other locales. It does not state when-not-to-use this tool (e.g. for existing articles, where update_article applies), so it stops short of full 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=false, idempotentHint=false and destructiveHint=false, but the description adds the concrete consequence of non-idempotency ('uploads another copy rather than replacing'), which is actionable beyond the boolean. It also compensates for the absent output schema by enumerating the returned fields. It does not mention auth/permission requirements, so not a full 5.

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

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

Three sentences, front-loaded with the core action and return value, followed by the important non-idempotency caveat and sibling routing. No filler; 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 write tool with no output schema, the description supplies what the schema cannot: the shape of the return value, the non-idempotency behavior, and disambiguation from related attachment tools. 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 description coverage is 100%, so the schema already documents all four parameters including base64 encoding, size limits and MIME type. The description adds no parameter-level detail beyond what the schema provides, 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 (upload) and resource (file to a Help Center article), and explicitly describes the return payload. It distinguishes itself from siblings by naming both get_ticket_attachments and list_article_attachments, so an agent can tell it apart without opening other 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?

Explicitly routes the agent: 'for files on support tickets use get_ticket_attachments' and 'to see an article's existing attachments use list_article_attachments.' Both the when-to-use and the alternatives are 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 declare the safety profile (not read-only, not idempotent, not destructive, open-world). The description adds meaningful context beyond them: the article-existence prerequisite, the no-existing-translation constraint (which effectively explains the non-idempotent behavior), and the return payload (locale, title, draft state). It does not mention permission/auth requirements, 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-loads the core action, then the prerequisites, the constraint with alternatives, and the input requirement. Every sentence carries distinct information with no 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 mutation tool with no output schema, the description covers the action, prerequisites, constraint, alternatives, required inputs, and even the shape of the returned translation. 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 description coverage is 100%, so all five parameters are already documented in the schema. The description only reinforces the body requirement ('full HTML body') and the locale/draft concepts, adding marginal meaning over the structured fields. 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 (create) and resource (article translation) scoped to a locale, and explicitly distinguishes itself from create_article (which creates the source article) and update_article_translation (which modifies an existing translation). An agent can route correctly 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?

Explicitly states the precondition (article must already exist, use create_article first), the constraint (target locale must not already have a translation), and names the two alternatives — update_article_translation for modifying and list_article_translations for discovering existing locales. Nothing 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavior beyond that: it discloses the return payload ('returns the created tag with its id') and implies a non-idempotent duplicate risk by recommending a lookup first. Permission requirements and the consequence of duplicates are not stated, keeping it short of a 5.

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 tightly written sentences: purpose first, then what it returns and the duplicate-avoidance workflow, then the contrasting alternative. Every sentence carries distinct information with no 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?

Despite having no output schema, the description states the return value ('the created tag with its id'), covers the create-then-attach lifecycle, and routes to the correct alternative for a closely related concept. 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?

Only one parameter, and schema description coverage is 100% with a clear description and example values ('billing', 'getting-started'). The description's 'end-user visible labels' phrasing reinforces the schema rather than adding new syntax or constraint detail, so the baseline 3 for fully documented schema 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 ('Create a new content tag for Guide articles') and immediately defines what a content tag is and how it differs from article labels, a sibling concept (list_labels). An agent can distinguish it from manage_tags and list_content_tags 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?

Gives an explicit pre-flight step ('check list_content_tags first, filter by name_prefix, to avoid duplicates'), the follow-up attachment path ('content_tag_ids of create_article or update_article'), and a named alternative for the when-not case (internal search-ranking labels → list_labels).

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/idempotent annotations, it discloses the cost (two listings), the coverage cap (100 categories and 100 sections, only first page past that, with a self-reporting caveat), the inactive-locale warning, and crucially that it reads the draft flag rather than trusting the listing. This is exactly the kind of behavior an agent cannot infer from 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?

Front-loads the purpose in the first sentence and keeps every clause information-bearing. The second sentence is a dense run-on with multiple em-dash clauses, which slightly hurts scannability, but no content is 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?

With no output schema, the description still tells the agent what the report contains (gaps plus the reason: missing vs unpublished draft) and its limits. Combined with the routing to fix tools, 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 100%, so the baseline is 3, but the description adds real meaning: it explains the tradeoff of omitting category_id (full sweep costs two listings, capped at 100/100) versus passing it to narrow the audit, and notes the inactive-locale warning behavior for locale.

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 (audit), resource (Help Center tree for a target locale), and precisely what it reports: categories/sections with no translation or only an unpublished draft. It is unambiguously distinguishable from the listing siblings like list_sections/list_articles.

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 (before/after translating articles) with the concrete motivating scenario of an article being unreachable while its parent section only exists in the source locale. It names the alternative (listing sections in that locale) and explains why it fails, and routes fixes to set_section_translation / set_category_translation.

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 readOnly, idempotent, and non-destructive behavior, so safety is covered. The description adds value beyond that by disclosing the return payload (body as HTML, metadata, source_locale, available translations) and the token-cost tradeoff, which the annotations do not express.

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 tight sentences, each earning its place: retrieval scope, routing alternative, locale option, return shape. It is front-loaded with the core action and contains 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?

There is no output schema, yet the description enumerates the return contents (body HTML, metadata, source_locale, translations). Combined with complete parameter coverage and annotation-backed safety, 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 description coverage is 100%, so both parameters are already documented in the schema (article_id even names its source tools). The description's note that locale fetches a translated version is a small addition but largely restates the schema's own 'Locale for translated version' text, 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 (Retrieve) and resource (an article) and clarifies scope: 'by ID with full body content'. It explicitly distinguishes itself from the sibling tools get_article_outline and get_article_section, so an agent can route 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?

Names the alternative tools (get_article_outline + get_article_section) and the exact condition that selects them ('For large articles ... to save tokens'). This is explicit when-to-use/when-to-prefer-alternative guidance, not merely 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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavioral value beyond annotations: it discloses the return shape (h1/h2/h3 sections with word counts) and that translations with outdated status are bundled in — non-obvious extra content the agent should expect.

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 with the primary behavior front-loaded and the sibling routing second. Every clause earns its place; 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?

With no output schema, the description does the necessary work of describing the return payload (sections, word counts, translation status), which is what an agent needs to decide to call it. What it omits — ordering, pagination, empty-article behavior — is minor for a read-only outline tool.

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

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

Schema description coverage is 100%, and both params (article_id, locale) are documented in the schema. The description only restates the locale default that the schema already states, adding no syntax or format detail beyond it, 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 ('Return a compact outline of an article') and details exactly what the outline contains — h1/h2/h3 sections with word counts plus translation/outdated status. An agent can distinguish it from get_article and get_article_section 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?

Explicitly routes the agent to a sibling: 'Use get_article_section to fetch a specific section,' which distinguishes outline-level vs section-level access. It stops short of stating when to prefer this over get_article for a full body, but the alternative is named with a selecting condition.

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 cover read-only/idempotent/non-destructive, but the description adds real behavioral context beyond them: markdown lossiness on specific structures (pre/br, multi-p table cells), the round-trip hazard with update_article_section, and the fact that the leading '## [n] hN:' line is a label rather than content.

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 purpose, then prerequisites, then format guidance. Every sentence carries information, though the middle format sentence is dense and could be trimmed 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?

With no output schema, the description does the work of describing what comes back in each format and warns about the lossy representation and label line. It stops short of covering error cases (e.g., invalid section_index) or whether nested subsections are included.

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 still adds meaning beyond the schema by explaining the risk profile of the markdown enum value and by documenting an undocumented aspect of the returned content (the label line at the top).

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 (Retrieve), resource (content of a single section of an article), and scope qualifiers (single section, given locale), which cleanly separates it from get_article and get_article_outline without ambiguity.

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

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

Explicitly names the prerequisite tool ('Use get_article_outline first to discover section indexes') and gives a conditional rule for the format parameter (html default vs markdown only for human review), including a when-not case (not before update_article_section).

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, idempotentHint, destructiveHint=false, and openWorldHint, covering the safety and mutation profile. The description adds the scope that this returns the authenticated user and a use case, but says nothing about auth requirements, rate limits, or return shape. With annotations doing the heavy lifting, 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 short sentences, front-loaded with the core action and followed by a brief use case. No filler or repetition; 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 simple, zero-parameter read tool with rich annotations and no output schema, the description gives the agent everything needed: what it retrieves, whose identity it targets, and why one would call it. No critical details are 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 takes zero parameters, so the rubric sets the baseline at 4. The schema is empty and the description introduces no additional parameter semantics, which is acceptable for a no-argument tool.

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 clear verb and resource ('Get the currently authenticated Zendesk user'), and the 'currently authenticated' scope inherently distinguishes it from sibling tools like get_user or search_users. However, it does not explicitly name an alternative, so it falls short of a 5 under the rubric.

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 use case: 'Useful to verify identity and permissions.' This tells the agent when to reach for the tool, but it does not state when not to use it or name alternatives such as get_user, so it lacks exclusion 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, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered by structured data. The description adds useful semantics about what is returned (incidents referencing the given problem) and the underlying Zendesk relationship model, but nothing on auth, scoping, or result 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 tight sentences with the core action front-loaded and the rationale trailing it. Nothing is wasted, though the parenthetical restatement of the relationship is slightly redundant with the opening clause.

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?

One required parameter, no nested objects, and no output schema, so the description carries a small burden. It correctly conveys the return content (a list of linked incidents) and the domain relationship, which is sufficient for an agent to call it correctly; only pagination/result-volume behavior 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?

Schema description coverage is 100%, and the parameter description already explains the ID's meaning and even points to search_tickets/list_tickets for obtaining it. The description adds little beyond 'the given problem,' so 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 ('Get all incident tickets linked to a problem ticket') and immediately clarifies the Zendesk problem/incident relationship. No sibling tool in the list performs this linkage retrieval, so the purpose is unambiguous and 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?

Explicitly gives the use case: 'useful to gauge a problem's blast radius before resolving it.' That is clear context for when to reach for this tool, but it names no alternatives or when-not conditions (e.g., use get_ticket for a single ticket's details).

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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuine value with no output schema present by naming the returned fields (name, tags, domains, notes) and noting it is richer than list/search results. It stops short of mentioning auth scope or failure modes for an invalid id.

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

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

Three short sentences with zero filler: purpose, payload differentiation, and the routing alternative, all front-loaded in that order.

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 single-param read tool with no output schema, the description covers purpose, routing, and field-level return content, which is enough to call it correctly. Missing only edge details such as behavior on an unknown id.

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 parameter is fully documented in the schema, including where to obtain the id. The description only echoes 'numeric id', so this is the baseline 3 for a schema that does the 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 (Retrieve) and resource (a single organization) with the keying constraint (numeric id), and explicitly contrasts the richer payload against what search or list_organizations return. An agent can distinguish it from list_organizations without opening either 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?

Explicitly routes the agent: use this for a known numeric id, use list_organizations to browse or do a name-based lookup. That names both the alternative and 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 declare a safe idempotent read, and the description adds substantial context beyond them: SLA is resolved via a scoped search and may be missing for very high-volume requesters or just-updated tickets, follower/CC lists come back empty when the 'CCs and followers' setting is disabled, and the appended comment block is unpaginated and char-limit-truncated. These are non-obvious behavioral traits that materially affect interpreting results.

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 purpose and then layered with caveats in a single dense paragraph. Every sentence carries real information, though the paragraph is long and the SLA/followers/comment caveats could be visually separated for faster scanning.

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 read tool with no output schema, the description covers the important gotchas: partial SLA availability, empty follower/CC lists under a setting, truncated comment threads, and sibling redirection. Nothing an agent needs to call and interpret this 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 schema already carries both parameters; the baseline is 3. The description goes slightly beyond by explaining the semantic consequence of include_comments (one unpaginated block, cut at the character limit, first page only) and where to get a ticket_id, adding marginal value over the schema text.

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 (retrieve a Zendesk ticket by ID) and enumerates the scope: SLA state, comments, followers, email CCs. It distinguishes itself from get_ticket_history and list_ticket_comments explicitly, so an agent can route without opening 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?

Explicitly names alternatives and the conditions selecting them: use get_ticket_history for change history, list_ticket_comments for paginated threads on long tickets, list_sla_policies for SLA target definitions. When-to-use and when-to-avoid are both present.

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 readOnly, idempotent and non-destructive, lowering the bar. The description adds genuinely useful return-shape context not covered by any output schema: images come back embedded inline while other files appear as text references, which affects how an agent should present results.

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

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

Two short sentences, zero filler, with the primary action front-loaded and the output-format nuance second. Every clause 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 usefully sketches the return format, and the schema fully documents both parameters. Gaps are minor: no mention of pagination or size limits and no routing to alternatives, but nothing required to invoke the tool 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 description coverage is 100% and the schema already explains ticket_id sourcing and that attachment_ids skips the comments fetch. The description adds no parameter 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 and resource ("Retrieve ticket attachments") that an agent can distinguish from article-attachment siblings like list_article_attachments by name. It does not explicitly call out the sibling boundary, but the ticket scope is unambiguous.

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

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

No guidance on when to use this tool instead of get_ticket(include_comments=true) or list_ticket_comments, and no mention of the attachment_ids fast path that skips the comments fetch. An agent must infer the workflow from the schema alone.

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 cover the safety profile (readOnlyHint/idempotentHint/destructiveHint), but the description adds substantial non-obvious behavior: system-generated notification events are filtered out (while CC-list edits are not), an update with only such events produces no entry, comments appear as presence markers not text, and pagination is oldest-first. This is rich behavioral context beyond structured fields.

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?

Dense and front-loaded, leading with what is returned before the filtering caveat and the usage guidance. It is long, but nearly every clause carries information; a small amount could be tightened without loss.

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?

No output schema exists, yet the description thoroughly specifies the return contents (actor name/id, channel, before→after field changes with ids resolved to names, comment presence markers) and the filtering semantics. An agent has everything needed to call and interpret this 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?

Schema coverage is 100%, so baseline is 3, but the description reinforces cursor direction ('pass the returned cursor to page ... toward its most recent changes') and explains that a page can render fewer entries than page_size due to event filtering. It adds meaning but largely parallels the already-detailed schema descriptions.

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

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

States a specific verb+resource ('Read a ticket's change history — its audit trail') and precisely characterizes the output shape (chronological oldest-first timeline of who changed what and when). It explicitly distinguishes itself from siblings by naming list_ticket_comments and get_ticket(include_comments=true) as the way to get comment bodies.

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 triggering questions ('what happened on this ticket?', 'why was it reassigned?', 'when did it go to pending?') and names the alternative tool for a related need (comment text). Also explains why to read oldest-first. This is explicit when-to-use plus 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds value by listing the returned fields, which matters since there is no output schema, but it does not address failure modes (e.g., not-found behavior) or permission requirements.

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: purpose first, then routing guidance. No redundant or filler content, and the lookup constraint is front-loaded.

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

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

For a single-parameter getter with full schema coverage, the definition covers purpose, key, return shape, and sibling routing. 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 description coverage is 100% and the single parameter already documents the numeric id plus where to obtain it (search_users, ticket requester/assignee). The description's mention of 'numeric id' merely reinforces the schema, 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 (retrieve) and resource (a single user) with the exact lookup key (numeric id), which distinguishes it from bulk/list siblings. It also enumerates the return payload (name, email, role, organization, tags).

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

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

Explicitly routes the agent: use search_users when only a name or email is available, and get_current_user for the authenticated identity. Both alternatives are named with the condition that selects them.

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 readOnly/idempotent/destructive=false, so safety is covered. The description adds real behavioral context beyond them: the no-match fallback returns available titles instead of erroring, results are cursor-paginated, and there is deliberately no SLA block. It stops short of describing auth requirements or any rate limits.

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

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

Front-loaded with the core action and ordered intuition, with fallback behavior and pagination appended where they belong. Dense but nearly every clause carries information; the SLA/parenthetical aside and the sort override reminder are the only parts that could be trimmed.

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?

No output schema exists, so the description must carry the return contract, and it does reference the field shape via list_tickets and notes cursor pagination. It leaves the exact field list implicit through that sibling reference, which is adequate but not fully self-contained for a 5-parameter 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 the baseline is 3, but the description adds cross-parameter meaning the schema states only in isolation: that title matching is case-insensitive against active views and that sort_by/sort_order operate as overrides of the view's configured order. It does not add format detail for cursor beyond what the schema says.

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?

Specific verb and resource ('Read the tickets inside a Zendesk view') plus scope (view's own configured sort order). It explicitly carves out territory against siblings: not list_tickets (same field shape but unfiltered), not search_tickets (no live SLA block). An agent can pick this tool without opening another 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?

Names the conditions that select this tool ('the natural way to work a named queue') and routes to alternatives explicitly: list_views to discover ids/titles, search_tickets when per-ticket SLA state is needed, sort_by/sort_order when a different cut is wanted. Both when-to-use and when-not-to-use are present.

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 read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely useful detail beyond that: it returns metadata only (id, name, content type, size, URL) rather than file bytes, and clarifies both inline and block attachments are included — a non-obvious inclusion rule.

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 return shape, then sibling routing. Every sentence earns its place with no 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 single-parameter list tool with no output schema, the description covers purpose, return contents, scope boundary, and sibling alternatives. 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 description coverage is 100% (article_id is fully documented), so the schema carries parameter semantics. The description adds no syntax, format, or filtering detail about article_id, so 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 all attachments for an article") and immediately scopes it to Help Center articles, distinguishing it from get_ticket_attachments and create_article_attachment. An agent can identify the correct tool 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?

Explicitly names the alternative for a different context ("for attachments on support tickets use get_ticket_attachments instead") and routes file creation to create_article_attachment. Both the when-to-use and the when-not-to-use are stated, not implied.

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 read-only, idempotent, non-destructive profile. The description adds real behavioral value beyond that: metadata-only returns, and the important caveat that include_translations must be re-sent on each paginated request (plus its per-article API cost).

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 in the first clause, then adds filtering, sorting, and the pagination caveat in tight, waste-free sentences. No redundancy that could mislead.

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 listing tool with no output schema and full schema coverage, the description supplies everything needed to call it correctly: scope, return granularity, optional filters, sorting, and the pagination re-send caveat.

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 schema already documents all seven parameters in detail. The description adds little, and its enumeration of sort_by values ("title", "created_at", "updated_at") is actually incomplete versus the schema, which also includes "position" as the default.

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 articles") and immediately bounds the scope ("metadata only, no body"). It also names the sibling get_article as the tool for full content, so an agent can distinguish the two without opening either 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?

Explicitly routes the agent to get_article when full content is needed, and describes the optional section/locale filtering context. It does not address when to prefer the sibling search_articles over this listing tool, so a routing gap remains.

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, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds real behavioral value by disclosing that only metadata is returned and enumerating which fields, which prevents an agent from expecting body content.

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

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

Two short sentences, zero waste, with the payload constraint front-loaded before the routing advice. Every clause 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 compensates by naming the returned fields, and the single parameter is fully documented in the schema. Nothing needed to call this tool 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?

There is one parameter and schema description coverage is 100% — the schema already explains article_id and where to obtain it. The description mentions 'locale' only as an argument to the sibling tool, adding nothing about this tool's own parameter, so 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 (list) and resource (translations for an article) and immediately scopes the payload: metadata only, no body, with the exact fields (locale, title, draft, updated_at). An agent can distinguish this from get_article or create_article_translation 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 names the alternative (get_article with locale) and the condition that selects it (full translated content). The 'metadata only, no body' framing also implicitly states when not to use this tool, though there is no explicit exclusion or prerequisite beyond that.

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 readOnly, idempotent, non-destructive, open-world, so the safety profile needs no repetition. The description adds genuinely new behavioral context: entries contain id/name/locale and results are cursor-paginated, which the annotations do not 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 followed by hierarchy, return shape, pagination, and parameters. Slightly dense with routing detail, but no sentence 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?

For a zero-required-param list tool with a fully documented schema and annotation-covered safety profile, nothing material is missing; return fields, pagination, locale behavior, and follow-up tools are all covered without an 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 coverage is 100%, so the baseline is 3; the description earns above baseline by explaining that locale controls the translation used for category names. It also reinforces the pagination model behind the cursor parameter, adding meaning beyond the field labels.

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 Help Center categories) and immediately locates it in the Guide hierarchy, distinguishing it from list_sections and list_articles. An agent can tell exactly what this returns and where it sits.

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 drill-down path (category id → list_sections → list_articles) and a condition for using the locale parameter. It stops short of stating when NOT to use it (e.g., when you already have a category id), but the routing context is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). Beyond that, the description discloses meaningful behavioral nuance: untranslated categories are omitted from list_categories while unpublished drafts may still appear there, and the draft flag here is authoritative. It doesn't cover pagination or exact return shape, but adds real 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 verb and resource, then adds only information that routes the agent correctly. It is on the longer side, but nearly every clause carries actionable distinction rather than 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 correctly describes the returned fields, and single-parameter input is fully covered by the schema. An agent has everything needed to select and invoke 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?

Schema description coverage is 100% and the single category_id parameter is already fully documented in the schema (including where to obtain it). The description adds no parameter-level 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 and resource ('List the translations of a Help Center category') and enumerates exactly what is returned per locale (localized name, description presence, published vs draft). It clearly distinguishes itself from siblings like list_categories and set_category_translation.

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 states when to reach for it ('when a category looks wrong in a locale') and why the obvious alternative fails (list_categories omits untranslated categories and lists drafts). It names the fix tool (set_category_translation) and the bulk alternative (find_translation_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, idempotentHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds non-obvious behavioral context beyond that: results are cursor-paginated and must be enumerated by following the returned cursor, and sorting defaults to name. It does not mention auth requirements or rate limits, but the pagination/ordering disclosure is genuinely additive.

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

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

Three sentences, each load-bearing: identity/scope first, then pagination and ordering behavior, then the lookup workflow and the sibling alternative. No filler, no restatement of the title, and the most decision-relevant facts are front-loaded.

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

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

For a read-only, paginated list tool, the description covers everything needed to call it correctly: what it returns, how to page through it, default ordering, the prefix-lookup workflow, and the boundary with list_labels. No output schema exists, but the description adequately characterizes the returned collection and its pagination contract.

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 that name_prefix is a prefix match rather than a fuzzy/substring search and the page_size cap of 30. The description paraphrases these rather than adding format or unit detail, so the baseline of 3 applies; the only extra is the workflow intent behind name_prefix, which is more usage than parameter semantics.

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 Guide content tags') and immediately defines the domain object as 'end-user-visible labels that help readers find related articles'. It explicitly separates itself from the sibling list_labels by scoping those as 'internal, non-end-user search labels', so an agent can route correctly without opening either 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 explicit when-to-use guidance: pass name_prefix and 'do this before create_content_tag to reuse an existing tag rather than fragment the taxonomy'. It also names the alternative tool and the condition that selects it ('For internal, non-end-user search labels, see list_labels'). Both a positive workflow and an exclusion are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond that: results are scoped by per-user OAuth to what the current user can see and no shared admin key is needed, plus the offset-paginated return shape.

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 is front-loaded in the first sentence, followed by definition, return shape, scoping and routing. It is denser than strictly needed (the macro definition sentence is long), but each clause carries information and nothing is redundant.

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 compensates by enumerating the returned fields, and it also covers pagination behavior, auth scoping, and the follow-up tool. An agent has everything needed to call and then chain this 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?

Schema description coverage is 100% and both parameters (page, per_page) are fully documented in the schema itself. The description only notes 'offset-paginated' generically without adding format or default details beyond what the schema already provides, 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 gives a specific verb (List) and resource (active macros), then defines what a macro is and what is returned (id, title, description, availability scope, ordered actions). It clearly distinguishes this from siblings like list_labels and list_views by describing the resource and its scope.

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

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

It explicitly routes the agent forward: 'Pass a macro id from here to preview_macro_diff to preview its effect on a specific ticket,' which is genuine when-to-use guidance for a sibling. It does not, however, state when this tool should NOT be used or contrast it against other listing tools beyond that single forward reference.

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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds value by disclosing the return shape (name/id plus basic fields) and that results are cursor-paginated, though it doesn't mention rate limits or page-size behavior beyond the 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 sentences, front-loaded with the core action and pagination, followed by alternatives and a brief domain note. Dense and mostly waste-free, though the closing sentence about organizations grouping end users is useful context rather than strictly essential.

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 appropriately fills the gap by naming returned fields and pagination semantics. It is nearly complete for a simple list tool; only finer pagination termination details are absent, which the cursor parameter largely covers.

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 both parameters (cursor, page_size) are fully documented in the schema. The description only restates 'with pagination' and adds no syntax or format detail beyond the structured fields, so 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 all organizations with pagination') and immediately names the returned fields, then explicitly distinguishes itself from get_organization and search. An agent can select this over its 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 explicit alternatives and the condition selecting each: use get_organization with an id for full details (tags, domains, notes), or search for query-based lookups by name. This is a clear when-to-use-this vs when-to-use-something-else 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?

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the use case but does not disclose return format, pagination, or any behavior 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?

Two short sentences with no wasted words. The purpose is front-loaded and the usage guidance follows directly.

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 no-parameter read-only list tool with rich annotations, the description is mostly sufficient: it states what is returned and why to call it. It could optionally mention the shape of returned records, but no output schema exists and the omission 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?

The tool takes no parameters, and the empty schema confirms this. Per the rubric, a zero-parameter tool has a baseline of 4 when schema coverage is complete.

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

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

The description uses a specific verb and resource: 'List all Guide permission groups.' It is clear what the tool does, though it does not explicitly contrast itself with sibling list tools such as list_labels or list_content_tags.

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

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

It gives a concrete usage context: 'Use this to find the permission_group_id required when creating articles.' That tells the agent when the tool is useful, but it does not mention exclusions or alternative 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds substantial non-obvious behavior: no server-side promoted filter, client-side filtering over up to ARTICLE_RESOURCES_SCAN_MAX_PAGES (default 20) API requests, no caching, and possible omission of promoted articles on very large Help Centers that is flagged in the output.

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 purpose and the get_article/update_article routing, then the cost model. It is dense and slightly long, but nearly every clause carries operational value; only minor tightening is possible.

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?

No output schema exists, and the description compensates by stating what is returned (metadata only, no body), that the default locale is used, and that truncation and page counts are surfaced in the output. Nothing an agent needs to decide whether to call it 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?

There are zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It does usefully clarify the implicit scoping behavior — that it lists the default locale — which an agent could otherwise assume was configurable.

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 promoted ("featured") Help Center articles') and narrows the scope precisely ('the small, editorially-curated set surfaced at the top of their sections'). It explicitly differentiates from siblings: 'use get_article for full content' and 'use update_article with `promoted`' to mutate.

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 explicit when-to-use (reading the curated featured set), when-not-to-use (full content belongs to get_article), the mutation alternative (update_article, with the admin-rights prerequisite), and a strong operational caveat to avoid repeated calls. Nothing 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 declare readOnly/idempotent/non-destructive, so the safety bar is low. The description adds real behavioral context the annotations lack: results are cursor-paginated and locale defaults to the Help Center default if omitted. It stops short of describing ordering or empty-page behavior.

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 purpose, then hierarchy, return fields, pagination and workflow in four tight sentences. Each sentence carries distinct information, though the hierarchy explanation is somewhat parenthetical to the call 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?

No output schema exists, but the description compensates by listing the returned fields, the pagination mechanism, and the default locale behavior. Combined with full schema coverage, an agent has everything needed to call it correctly on the first try.

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 schema already documents cursor, locale, page_size and category_id with types, defaults and bounds. The description largely restates these ('ids come from list_categories', 'pass a locale'), adding only light sourcing context rather than new semantics. 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 ('List Help Center sections') and situates it precisely in the Guide hierarchy (category → section → article), which cleanly separates it from siblings list_categories and list_articles. It also enumerates the returned fields, so an agent knows exactly what it gets.

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: pass category_id (which comes from list_categories) to scope to one category, then use a returned section id with list_articles. This names the prerequisite call and the downstream call, covering both when and how to use it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantive behavioral context beyond them: untranslated sections are omitted from listings, and draft translations may appear under the draft name, so 'listed' does not imply 'published'. It also discloses the shape of the returned data without an 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?

Front-loaded with purpose and the returned fields, then the usage scenario and routing. The middle clause explaining the draft-listing nuance is dense but load-bearing rather than padding, so the length is justified even if the sentence is somewhat convoluted.

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 compensates by describing the returned fields, and it supplies the parameter's origin, the disambiguating rules, and both follow-up routes. An agent has everything needed to call it correctly and interpret the result.

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 section_id parameter is already documented in the schema, including its source (list_sections or the topology resource). The description adds no further syntax or format 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 and resource ('List the translations of a Help Center section') and enumerates the returned fields (localized name, description set, published/draft). It explicitly distinguishes itself from the sibling list_sections by naming the exact situation where the two differ.

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 trigger ('when a section looks wrong in a locale'), explains why the obvious alternative (list_sections) cannot answer the question, and names both the remediation tool (set_section_translation) and the bulk alternative (find_translation_gaps). Nothing about when-to-use vs alternatives 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 declare readOnly/idempotent/non-destructive, so the description correctly focuses on what annotations cannot convey: the admin-token requirement and the concrete 403 failure mode for standard agent tokens, plus the workaround. It stops short of describing pagination behavior or output shape details beyond the field list, but the auth disclosure is genuinely additive.

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 resource and payload, then usage, then access constraints. Two sentences with no filler, though the second sentence is dense and could be split for readability.

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 carries the return-value burden and does so at a summary level (filters + per-priority targets) while covering auth and pagination. Adequate for a read-only list tool, short only of exact field-level detail.

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 both page/per_page descriptions already explain offset pagination, total-count headers and the 100 cap. The description adds nothing about the parameters, 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?

Specific verb+resource ("List the configured SLA policies") plus a precise statement of what is returned: filter conditions and per-priority reply/resolution targets. An agent can distinguish it from get_ticket/search_tickets, which return per-ticket SLA state rather than the policy matrix.

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 states the use case (explain why a target applies, reconstruct deadlines instead of hard-coding the matrix) and names the alternative path for live per-ticket SLA via get_ticket / search_tickets. Both when-to-use and the fallback are given.

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 cover the safety profile (readOnly, idempotent, non-destructive), so this adds context instead: the truncation behavior of the alternative tool and which end it drops, cursor invalidation when sort_order changes, and the deliberately small default page size rationale. These are non-obvious operational traits an agent cannot infer from annotations or 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?

Front-loaded with purpose and returns, followed by tool routing and parameter guidance — a sensible ordering. It is dense and the final sentence runs long, but each clause carries a distinct routing or behavioral fact rather than 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 enumerates the returned fields (comment id, resolved author name, timestamp, public/internal flag, attachment ids), and it covers pagination, ordering, and sibling alternatives. An agent has everything needed to invoke and use the result 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%, so much of the parameter detail duplicates the schema (cursor semantics, page_size bounds, sort_order enum). The description still adds decision-level guidance — keep the default 'desc' for the latest reply, follow the cursor rather than raising page_size — which is meaning beyond the raw 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?

States a specific verb and resource ('Read a ticket's conversation — public replies and internal notes with their full bodies') and immediately scopes the retrieval model (cursor-paginated, newest first). It explicitly distinguishes itself from get_ticket, get_ticket_history, and get_ticket_attachments by name.

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

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

Gives an explicit routing rule: 'Prefer this over get_ticket(include_comments=true) whenever a thread is long or you only need the latest exchange,' and explains why (unpaginated block truncated past the character limit, dropping newest comments). It also routes field-change history to get_ticket_history and file downloads to get_ticket_attachments.

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 cover readOnly/idempotent/destructive, so the safety profile is known. The description adds real value beyond them: the exact returned attributes (id, type, active/required, dropdown option values) and pagination behavior ('cursor-paginated in Zendesk's default field order'). It stops short of richer detail like rate limits or total-count semantics, so 4 rather than 5.

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 what it returns, then why to call it, then behavioral notes. Three dense sentences with no filler; every clause 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?

No output schema exists, so the description carries the burden of explaining return values, and it does so concretely (id, type, active/required, option values). Combined with the pagination note, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so cursor and page_size are fully documented in the schema itself. The description only alludes to pagination generally and adds no syntax or format detail 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?

Specific verb (List) plus resource (ticket field definitions) with explicit scope: system fields and custom fields, plus the returned attributes. It is immediately distinguishable from siblings like list_labels, get_ticket, or create_ticket.

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 states when to use it: to discover numeric field ids and option tags that create_ticket and update_ticket expect in custom_fields, with a concrete example ('set severity to High'). This routes the agent to the correct tool and names the downstream 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds non-obvious behavior: results are ordered by ascending id rather than recency, and pagination is cursor-based via a returned cursor. It omits details like rate limits or total-count behavior, so it stops short of a 5.

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 front-loaded sentences with zero filler: ordering/nature first, pagination mechanics second, alternative tool routing last. Every clause carries decision-relevant information.

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

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

For a two-parameter list tool with no output schema, the description covers ordering, pagination mechanics, and sibling routing, which is close to everything needed. It does not describe the returned ticket shape or cursor header/field name, a minor remaining gap.

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

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

Schema coverage is 100%, so both parameters are already documented and the baseline is 3. The description goes further by clarifying that page_size (not per_page) controls page size here and that the cursor is returned by the previous response and passed back to paginate, adding real semantic value beyond the schema.

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

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

States a specific verb and resource plus the exact ordering semantics ('Zendesk's default order (ascending ticket id), not by recency'), and explicitly names the sibling it is not (search_tickets). An agent can distinguish it from the many list_*/get_* 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 explicit when-to-use routing: use this for cursor-based enumeration, use search_tickets with a query to find tickets by recency or any other criterion. It even warns that search_tickets uses per_page instead of page_size, which is exactly the disambiguation an agent needs.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered by structured data. The description adds domain context ('segments control article visibility'), but says nothing about pagination, result size, or whether the list is exhaustive for the workspace.

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 core action, followed by the meaning of the resource and how the output is consumed. 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 zero-parameter, read-only list tool with no output schema, the definition covers what it returns conceptually (segment IDs) and how they are used. Minor gap: it does not describe the shape of each returned segment beyond the ID.

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 the baseline is 4. There are no parameter semantics to explain, and the description correctly avoids inventing any input requirements.

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+resource ('List all user segments') and goes further by explaining what a segment is ('control article visibility (who can view)'). It does not name a sibling or explicitly distinguish itself from adjacent listing tools like list_permission_groups, so it stops short of a 5.

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

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

It hints at downstream usage ('Use the ID when creating or updating articles'), which tells the agent why the result matters, but it never states when to prefer this tool or what alternatives exist (e.g., permission groups vs. user segments). The guidance is implied rather than explicit.

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/idempotent/non-destructive annotations, it discloses genuinely non-obvious behavior: per-agent scoping tied to per-user auth, counts served from Zendesk's cache with up to ~1 hour lag, and the '(count updating)' sentinel state. These are exactly the gotchas an agent needs and are not derivable from structured fields.

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 and keeps to one dense paragraph where each clause (examples, counts, scoping, staleness, hand-off) carries information. Slightly long and clause-heavy, but no filler sentences.

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 still conveys the return shape (views each with a ticket count) and the caveat about stale counts. Combined with the annotated safety profile and a fully covered 2-param schema, nothing needed 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 description coverage is 100%, so cursor and page_size are already fully documented in the schema. The description adds no parameter-level detail (no mention of pagination or page-size tradeoffs), 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 Zendesk views) and immediately grounds it with concrete examples ('Unassigned tickets', 'My open tickets') and the payload (views with current ticket counts). It also names the sibling get_view_tickets as the follow-up tool, so an agent can distinguish it without opening either 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 signals the context of use ('tell at a glance where the workload sits') and hands off explicitly to get_view_tickets for drilling into tickets. It lacks an explicit when-not-to-use statement or a mention of list_tickets/search_tickets as alternatives, so it stops short of 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 declare idempotent/destructive/openWorld, but the description adds the mechanism the annotations cannot express: an incremental read-modify-write that merges rather than replaces, collapses duplicates, leaves unlisted tags untouched, and returns the full post-update tag set. This is exactly the kind of beyond-annotation context that prevents data loss.

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, then mechanics, then routing to alternatives. Dense and mostly waste-free, though the mechanics and idempotency points could be trimmed by a sentence without losing meaning.

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

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

Though there is no output schema, the description states the return value ('full tag set after the update'), the mutation semantics, and the sibling routing. Nothing an agent needs to call this correctly and 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 already documents add/remove omission and no-op semantics, so the baseline is 3. The description goes slightly beyond the schema by stating the merge/duplicate-collapse behavior and that unlisted tags survive, which clarifies how the two arrays interact.

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 pair and resource ('Add or remove tags on a ticket') and immediately names the sibling it is not for ('to overwrite the entire tag set at once ... use update_ticket instead'). An agent can distinguish it from update_ticket or create_content_tag 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?

Explicit when-to-use ('incremental tag edits') plus an explicit when-not with the named alternative (update_ticket for overwrite or combined field changes). It even tells the agent how to obtain the required ticket_id via search_tickets or list_tickets.

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 annotations: it explains the two underlying reads (current ticket + macro-apply preview), that unchanged/identity fields are omitted, the exact returned shape (status, priority, assignee, group, tags, custom fields + reply with public/internal flag), and that nothing is persisted. The idempotentHint=true is consistent with a stateless preview.

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?

Dense and front-loaded: the no-save guarantee and returned-fields summary come first, followed by the follow-up path and id sourcing. The rationale sentence about the 'deliberate two-step' is mildly editorial but still earns its keep by justifying the design.

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 carries the burden of describing the return value, and it does so precisely (only changed fields, reply with its visibility flag, omissions noted). No annotation or schema gaps remain for an agent to call and interpret this 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?

Schema description coverage is 100%, so both integer parameters are already documented in the schema, including where to obtain them. The description repeats that sourcing guidance but adds no syntax or format detail beyond the schema, 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?

Specific verb (preview) + resource (macro diff on a ticket) with explicit scope: it returns only the fields the macro changes plus the canned reply, and commits nothing. This distinguishes it cleanly from update_ticket, which is named as the actual mutator.

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?

States exactly when to use it (to see a macro's effect before applying) and routes the agent to update_ticket, add_public_comment, and add_private_note for the follow-up write. It also names list_macros, search_tickets, and list_tickets for obtaining the required ids.

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/readOnlyHint=false/idempotent, but the description goes well beyond them: it explains the position-0 tie ambiguity that motivates minimal writes, discloses that auto-sorted sections silently ignore writes and how that is detected after the fact, and describes the threshold-based refusal requiring confirm. These are non-obvious behavioral traits an agent cannot infer from structured fields.

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 scope, then layered caveats, with zero filler sentences. It is dense and slightly long, but nearly every clause carries decision-relevant information.

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

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

Covers the action, the exclusion, the failure mode (auto-sorted sections), the safety gate, and even the return value ("return whether the new order was applied") in the absence of an output schema. Nothing needed 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 description coverage is 100%, so every parameter including target, confirm, and normalize is already documented in the schema. The description restates the confirm/threshold behavior but adds nothing beyond the schema and never mentions normalize. Baseline 3 is appropriate when 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 and resource (reorder an article within its current section) plus the precise mechanism (relative to siblings: top, bottom, before/after). It explicitly contrasts itself with the sibling update_article for cross-section moves, so an agent can distinguish it 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?

Explicitly names the trigger scenario ("put this article first/last" requests) and the alternative (update_article with section_id) for the case this tool does not cover. It also states the automatic-sorting condition under which the tool will not work, which is exactly the kind of when-not guidance that prevents wasted calls.

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, idempotentHint, openWorldHint, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: return shape (total count), pagination size (100 per page), and the important limitation that organization results carry only name and ID. It does not mention rate limits, but the added result-shape detail is substantive.

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

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

Three sentences, front-loaded with the primary purpose, then filters, then return behavior and the get_organization redirect. No filler, though the sentences pack several distinct ideas each.

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?

No output schema exists, so the description carries the return-value burden and does so reasonably: total count, pagination, and limited org fields. For a read-only search tool with full schema coverage, this is nearly complete; a note on result ordering or rate limits would close the gap.

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

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

Schema description coverage is 100%, so all three parameters are already documented with pagination semantics and filter syntax. The description's filter examples ('type:ticket status:open') largely duplicate what the query schema field already states, adding little beyond the structured data. 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 the three resource types it spans (tickets, users, organizations), which is clear and actionable. However, it never distinguishes itself from the sibling search_tickets and search_users tools, so an agent cannot tell from the description alone when this unified search is preferred over the narrower ones.

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 naming the three searchable types and by the redirect 'use get_organization for full details', which covers one downstream alternative. There is no explicit guidance on when to prefer this over search_tickets/search_users, and no stated prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely useful context not in the annotations: results are metadata only and exclude article bodies, and the response reports a total count. It does not disclose ranking behavior or empty-result handling, so it is solid but not rich.

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

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

Three short sentences with zero filler; the scope constraint (metadata only) and the alternative tool are front-loaded before secondary details like locale and count.

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 states that a total count is returned, and annotations carry the safety profile. Pagination and query semantics live in the schema. What is missing is only marginal – ranking/relevance behavior and how results are ordered.

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% – each of the four parameters is documented in the schema, including pagination mechanics. The description only echoes locale filtering, which the schema already explains, so a 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 ('Full-text search across Help Center articles') with an explicit scope qualifier ('metadata only, no body'). It also names the sibling tool that serves the complementary need (get_article), so an agent can distinguish it without opening either 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?

Explicitly routes the agent to get_article when full content is needed, and notes locale filtering is supported. However, it gives no guidance on when to prefer this over list_articles/list_sections or other sibling listing tools, so the exclusion set is partial.

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 readOnly/idempotent/non-destructive safety, and the description adds real behavioral value: SLA enrichment on each result and a total count in the response. It doesn't discuss pagination limits, but the schema covers that, so this is above baseline.

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 and SLA behaviour before examples. The parenthetical SLA clause is information-dense but slightly heavy; nothing 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?

For a read-only search tool with a fully documented schema, no output schema, and annotations covering the safety profile, the description supplies everything needed: query syntax, the SLA shape of results, and the total-count return.

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 query/page/per_page semantics are already fully documented. The description's examples of valid query syntax are helpful but largely overlap what the schema's query description states, so 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 (search tickets) plus a distinctive capability: results carry live SLA state per metric. This clearly separates it from list_tickets, get_ticket, and the generic search 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 concrete query examples and a clear use case ('breaching today' queue triage without a per-ticket fetch), which tells the agent when this tool is the efficient path. It never explicitly names exclusions or the alternative sibling (list_tickets), 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds only 'Returns total count' and the note that query syntax is expected; it says nothing about pagination limits or result ordering beyond what the schema documents.

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

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

Two short sentences, front-loaded with the core verb/resource and no filler. 'Returns total count' is a slightly weak closer given there is no output schema to compare against.

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 carries the burden of describing the response, and it only mentions the total count, leaving result shape, ordering, and pagination semantics to the schema. For a three-parameter search tool it is minimally adequate but not complete.

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

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

Schema description coverage is 100%, and the schema documents page, per_page, and query syntax in detail, so the baseline is 3. The description restates the query capabilities ('name, email, or other criteria') without adding format, syntax, or constraint detail beyond the schema.

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

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

States a specific verb and resource ('Search for users') plus the query mechanism, so an agent knows exactly what this returns. It does not distinguish itself from generic siblings like `search`, `search_tickets`, or `search_articles`, but the 'users' resource is unambiguous.

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

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

No when-to-use guidance at all: nothing says to prefer this over the generic `search` sibling, nor when to reach for `get_user` (exact lookup) versus this query tool. The agent must infer the choice entirely.

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 annotations by disclosing upsert semantics (creates when absent, updates otherwise), partial-write semantics ('only the fields you pass are written'), and draft toggling as a one-call publish. It does not address permissions/auth or the destructiveHint in terms of what an unintended write could overwrite, but the partial-write and omit-to-preserve rules cover most of that risk.

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, front-loaded with the upsert behavior and return shape before the routing hint. Every sentence carries information, though the third sentence is long and slightly overloaded with sibling references.

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?

No output schema exists, yet the description names the return payload (locale, localized name, draft state). Combined with the upsert, partial-update and draft rules, an agent has everything needed to call it correctly without a prior listing 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter workflow meaning the schema does not: the draft:false single-call publish pattern, and the create-vs-update distinction that determines when name is required. That interpretation is genuinely useful rather than a restatement.

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 precise verb+resource+scope: create or update the translation of a Help Center category in one locale. It explicitly distinguishes itself from the sibling translation tools by calling out the category-level, single-locale scope and by naming find_translation_gaps and list_categories as adjacent but insufficient.

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 explicit when-to-use ('make a category reachable in a locale where its sections or articles are already translated'), names the sibling tools that report or cannot resolve the problem (find_translation_gaps, list_categories), and preempts the common alternative of calling a listing call 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 mark it destructive and idempotent, and the description adds real behavioral context beyond them: it creates vs updates depending on existing locale, writes only passed fields (partial update), and notes that 'publish this draft' is a single draft: false. That is exactly the mutation-safety and side-effect detail an agent needs.

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 dense sentences, front-loaded with the core action and outcome, then usage. Every clause carries information (upsert, return value, partial write, publish shortcut, routing), though the second sentence packs several ideas tightly.

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?

No output schema exists, yet the description names the return fields (locale, localized name, draft state). Combined with 100% schema coverage for inputs and annotations covering the destructive/idempotent profile, nothing needed 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 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema states only per-field: omitting name/description leaves them untouched, and draft:false publishes. The draft publishing interaction is the key operational detail and it is surfaced in prose.

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 pair (create or update), the resource (Help Center section translation), and the scope (one locale), and it returns the resulting translation. The 'section' resource cleanly separates it from set_category_translation and create/update_article_translation without needing schema inspection.

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 when-to-use ('make a section reachable in a locale where its articles are already translated') and ties it to the sibling find_translation_gaps. It implies the upsert removes the need for a prior listing call, but does not explicitly state when a different translation tool (category/article) is the right choice.

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 substantial behavior beyond the annotations: server fetches current body, reconstructs and PUTs the full body via the Translations API, strips a duplicated leading heading, and warns that other h1-h3 in content spawn new sections and shift later indexes. That index-shifting side effect is exactly the non-obvious behavior an agent needs before writing.

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 replace semantics, then side-effect warnings, then the format guidance. Dense but every sentence carries operational information; slightly verbose but not 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?

No output schema exists, yet the description pre-announces the response warning about index shifts, and covers the reconstruction/PUT mechanics, locale scoping, and content format expectations. For a destructive mutation tool this is 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 coverage is 100%, so the baseline is 3, but the description genuinely enriches it: section_index 0 is defined as the heading-less intro, and content's heading/label-line exclusion and format trade-offs are explained beyond the schema text.

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 ('Replace the body of one article section') and scopes it precisely: heading excluded, one locale, rest of article intact. This cleanly separates it from update_article (whole article), update_article_translation, and set_section_translation.

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 explicit conditional guidance for format (default html for fidelity; markdown only when you control input) and explains when section_index 0 exists. It does not name sibling alternatives to route between (e.g. full-article vs per-section updates), so it stops short of a full when/when-not/alternative map.

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, idempotentHint=true, and openWorldHint=true. The description adds real value beyond them by explaining WHY it is destructive: it 'replaces the FULL body and re-sends the entire article on each write.' It does not cover permission requirements or the omit-to-leave-unchanged semantics, but the core behavioral trait is disclosed.

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 no filler; the destructive full-body replacement caveat and the sibling alternative are front-loaded before the locale guidance.

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 write tool with no output schema, the description covers the replacement behavior, the sibling alternative, and locale semantics. Only minor gaps remain (e.g., no mention of permission/auth requirements), which annotations partially cover.

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 including the source_locale/locale relationship. The description's locale guidance largely restates what the locale schema entry says, so 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 ('Update article content (title, body) in a specific locale') and distinguishes itself from the closely-named siblings update_article and update_article_section. An agent can tell what it does and how it differs from neighboring tools.

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

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

Explicitly names the alternative ('prefer update_article_section' for targeted edits) with the exact condition that selects it. Also gives positive routing guidance for locale selection ('Use the article's source_locale from get_article... or another locale for translations').

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