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

Annotations indicate non-readonly, non-destructive, non-idempotent. The description adds behavioral context: note is appended to the ticket thread, and file attachments are uploaded via the Zendesk Uploads API. No contradiction.

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

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

Two sentences with front-loaded purpose and no wasted words. Every sentence adds value.

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

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

For a 3-param tool with no output schema, the description covers the main action, distinguishes from sibling, and mentions attachment mechanism. Could mention return value behavior, but it's not required.

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

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

Schema coverage is 100%, and the schema already describes parameters in detail. The description adds minimal extra meaning beyond restating 'internal note' and 'optionally with file attachments', which is baseline.

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

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

The description clearly states the verb 'Add' and resource 'internal note to a ticket', and explicitly distinguishes from sibling 'add_public_comment' by specifying visibility to requester.

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

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

The description provides explicit guidance on when to use this tool vs the alternative 'add_public_comment', stating 'use add_public_comment instead when the reply should be visible to the requester'.

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 indicate non-readOnly (write) and non-destructive. The description adds that the comment is appended to the ticket thread and emails the requester, which are key behavioral details beyond the annotations.

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

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

The description is concise, with only two sentences. The first sentence states the primary action and optional attachments; the second covers behavioral effects and the alternative tool. No wasted words.

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

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

The description covers the main behaviors (comment creation, emailing, attachments) and distinguishes from the sibling. It does not mention permissions or rate limits, but given the tool's simplicity and the presence of annotations, it is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the attachment mechanism ('uploaded via the Zendesk Uploads API and carried on the comment') and confirming that body text is sent to the requester and supports HTML.

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

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

The description clearly states the tool adds a public comment to a ticket, specifies it is visible to the requester, and optionally includes file attachments. It directly distinguishes itself from the sibling tool 'add_private_note' by contrasting public vs. internal notes.

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

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

The description explicitly tells the agent when to use this tool (adding a public comment) and when not to (use 'add_private_note' for internal notes). It also explains that attachments are handled via the Zendesk Uploads API, providing implementation 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 provide destructiveHint=true and idempotentHint=true. The description adds important context: soft-delete behavior, reversibility from admin UI, invisibility to end users, and return of confirmation message. It does not contradict annotations and provides value beyond them.

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

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

The description is concise with three well-structured sentences. It front-loads the main purpose, then provides details on behavior, alternatives, and prerequisites without superfluous content.

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

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

Given the rich input schema (2 params with 100% description coverage) and annotations, the description covers all necessary aspects: purpose, behavior, return type, alternative, and safety. No gaps are evident.

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%, but the description adds meaning by explaining 'confirm' as an explicit safety guard and 'article_id' as a numeric ID obtainable from list_articles or search_articles, which aids the agent in parameter selection.

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

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

The description clearly states 'Archive (soft-delete) a Help Center article' and distinguishes between soft-delete and permanent deletion, as well as from unpublishing via update_article. It specifies the verb (archive) and the resource (Help Center article) with detailed behavior.

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

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

The description explicitly states when to use this tool (the only removal API offers) and when not to use it (for temporary hiding, use update_article). It provides an alternative and explains the required confirm flag as a safety guard.

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

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

Annotations indicate read-only, open world, idempotent, non-destructive. Description confirms read-only nature, specifies three GET calls, and explains limitations (e.g., outdated flag set via native workflow, not API edits). No contradiction.

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

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

Lengthy but well-structured with numbered sections. However, some details (e.g., 'per-index rows may be misaligned') could be simplified without losing clarity. Still, it is organized and readable.

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, but description fully details all return signals: freshness verdict, outdated flag, structure check, per-section table, word counts. Also clarifies that word-count gaps are informational and not divergence indicators.

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

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

Schema covers 100% of parameters with descriptions. The tool description adds minimal new info beyond the schema, e.g., 'obtain from list_articles or search_articles'. 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?

Clearly states the tool compares two locales to decide if target translation needs work, listing five distinct signals. It distinguishes from sibling tools like get_article or list_articles by focusing on comparison and staleness detection.

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 describes when to use (compare translations for staleness) and notes it is read-only with three GET calls. Does not explicitly state when not to use or compare to alternatives, but the unique purpose makes this less critical.

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 indicate the tool is a mutation (readOnlyHint=false) and not destructive. The description adds that the locale becomes the source_locale, but this is also in the schema. No additional behavioral traits (e.g., side effects, rate limits) are disclosed beyond what annotations and schema 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 sentences with front-loaded purpose: 'Create a new article in a section and return the created article with its id.' Every sentence serves a purpose without 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?

With 11 parameters and no output schema, the description is minimal. It covers the return value ('with its id') and the key required parameter, but doesn't explain optional parameters like draft, promoted, etc. However, schema covers all parameters, so the description is adequate but not rich.

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 baseline is 3. The description only mentions 'permission_group_id' and 'locale' as source_locale, which repeats schema info. No new meaning is added beyond what the input schema already provides.

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

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

The description clearly states 'Create a new article in a section and return the created article with its id.' It specifies the verb (create) and resource (article), and distinguishes from sibling 'create_article_translation' by noting that for other locales, that sibling should be used.

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

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

The description provides explicit guidance on the required 'permission_group_id' and how to find it using 'list_permission_groups'. It also directs to 'create_article_translation' for adding content in other locales, giving clear context on when to use this tool versus 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?

Description discloses non-idempotency, which is critical beyond annotations. Annotations only show idempotentHint=false, but description explains the behavior (each call uploads another copy). Also mentions return value contents.

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 with no wasted words. First sentence states purpose and returns, second explains non-idempotency, third provides sibling differentiation.

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

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

Given no output schema, description adequately covers return values. It could mention potential size limits or authorization, but overall complete for a create attachment 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 schema already describes parameters well. Description adds no additional parameter details beyond the return value 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?

Description explicitly states 'Upload a file to a Help Center article and return the created attachment', with specific verb and resource. It also distinguishes from sibling tools by naming get_ticket_attachments and list_article_attachments.

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?

Clear guidance on when to use this tool (for article assets) and when not (for support tickets, use get_ticket_attachments; to view existing attachments, use list_article_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 indicate non-read-only and non-destructive. Description adds the return value (locale, title, draft state) but not more behavioral details like permissions or side effects.

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

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

Three concise sentences: purpose, constraints, and output. No redundancy, 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?

No output schema; description explains return fields. Preconditions and alternatives are covered. Could add example of locale format, but sufficient given complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context: 'target locale must not already have a translation' and 'Provide the full HTML body', adding meaning beyond schema.

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

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

The description clearly states the action ('Create a translation'), resource ('for an existing article'), and constraints ('in a specific locale'). It distinguishes from siblings by naming create_article, update_article_translation, and list_article_translations.

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

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

Explicitly states when to use (existing article, new locale), when not to (locale already has translation), and alternatives (use update_article_translation to modify, list_article_translations to check).

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 present; description adds that it returns the created tag with its id and implies mutation. Does not contradict annotations. Additional context about duplicate avoidance improves transparency.

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

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

Two sentences plus one extra: first states purpose/return, second gives usage guidance, third provides alternative. No redundancy, front-loaded, every sentence adds value.

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

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

For a simple one-parameter create tool with no output schema, the description covers purpose, return value, pre-use check, post-use attachment, and alternative. Complete given complexity.

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

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

Schema has 100% coverage for parameter 'name' with a clear description. Description adds context about using name_prefix for duplicate checking but does not provide new parameter semantics beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states 'Create a new content tag for Guide articles.' with specific verb and resource. It distinguishes from sibling tools by noting content tags are end-user visible labels, and contrasts with internal labels via list_labels. Also mentions return value includes the id.

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

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

Explicitly advises to check list_content_tags first to avoid duplicates, then attach via create_article/update_article. Also specifies alternative: for internal search-ranking labels use list_labels. Clear when to use and when not.

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 provide basic safety flags (not read-only, not destructive). Description adds behavioral details: 'The description becomes the first public comment of the ticket, and the new ticket id is returned.' Also explains tag formatting (lowercase, underscore). No contradiction.

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

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

Three sentences: first states purpose, second explains key behavior (first comment, returned id), third provides alternative tool guidance. Front-loaded, no waste.

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

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

With no output schema, the description explains that the new ticket id is returned, which is sufficient. It covers creation behavior, provides guidance on field IDs, and mentions related tools. Minor gap: no mention of error handling or rate limits, but overall adequate for an 8-param creation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats some schema info (e.g., description becomes first comment) and adds the return of ticket id, but no unique parameter insights beyond what the schema already provides for each property.

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

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

The description clearly states the tool's purpose: 'Create a new Zendesk support ticket with subject, description, and optional priority/type/assignee/tags.' It distinguishes from sibling tools like update_ticket, add_public_comment, etc., by noting they are for post-creation actions.

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 (to create a new ticket) and when not to (after creation, use other tools). Also provides guidance on how to find valid IDs via search_users, list_ticket_fields, etc.

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, the description discloses the tool's cost ('Costs two listings'), its hard limits (100 categories/sections, with truncation 'the report says so'), and its internal approach (reads the draft flag on each node). This is substantial and consistent with annotations.

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

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

The core purpose is front-loaded in the first sentence, but the later motivational example about unreachable articles could be tightened. Still, every remaining sentence conveys necessary operational detail, so it is concise enough for a complex audit tool.

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

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

The description thoroughly covers what, when, why, and operational limits, but with no output schema it stops short of specifying the report's exact structure (fields, how 'missing' vs 'draft' are marked). That missing detail is the main gap; otherwise it's highly 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. The description adds value by explaining the consequence of omitting category_id (whole-tree sweep with limits) and the importance of an active locale, which goes beyond the schema's descriptions without over-explaining.

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

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

The description opens with 'Audit the Help Center tree for a target locale' — a specific verb, resource, and outcome — and explicitly contrasts with sibling listing tools by explaining why 'listing sections in that locale cannot answer this.' This clearly distinguishes the tool from list_categories and list_sections.

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 explicit timing ('Use it before or after translating articles'), explains why alternatives fail, and names follow-up tools ('Fix what it reports with set_section_translation / set_category_translation'). It also advises passing category_id to narrow scope when hitting the 100/100 limit.

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

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

Annotations indicate readOnly, idempotent, and non-destructive. Description adds that it returns body (HTML), metadata, source_locale, and available translations, giving context beyond 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?

Four sentences, each adding distinct information: purpose, alternative guidance, optional parameter, return values. No wasted words, front-loaded with the core action.

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

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

Given two parameters and no output schema, description completely covers what the tool does and what it returns, including guidance on when to use alternatives. No gaps.

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%. Description adds meaning: for article_id, it explains where to obtain it; for locale, it clarifies it's optional and for translated version. This adds 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?

Description explicitly states 'Retrieve an article by ID with full body content', using a specific verb and resource. It distinguishes itself from siblings like get_article_outline and get_article_section, providing clear differentation.

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 explicit guidance: for large articles, prefer alternatives to save tokens; optionally specify locale for translation. While it doesn't explicitly state when not to use it, the alternative advice is strong and clear.

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

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

Annotations already declare readOnly and idempotent hints. Description adds value by mentioning inclusion of translations with outdated status, providing behavioral context beyond 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?

Two succinct sentences: first defines purpose and output, second provides usage guidance. No wasted words.

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

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

With no output schema, description hints at return format (compact outline, translations). Parameter count is low and coverage high. Adequate for a read-only 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%, but description adds context: locale defaults to source_locale, and article_id can be obtained from list_articles or search_articles.

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?

Clearly states 'Return a compact outline of an article' with specifics about sections and word counts, and distinguishes from sibling 'get_article_section'.

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 an alternative tool (get_article_section) and implies when to use this tool to get an outline, though lacks explicit when-not-to-use conditions.

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, etc. Description adds crucial behavioral details: default format='html' for round-trip safety, markdown is lossy on specific structures (<pre> with <br>, tables with multi-<p> cells), and explicitly states markdown does not round-trip. No contradictions with 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?

Description is three sentences, front-loaded with purpose. Each sentence earns its place: purpose, prerequisite, format guidance. No redundant or vague wording.

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

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

Given tool complexity (4 params, no output schema, rich annotations), the description is complete. It explains prerequisites, format trade-offs, and warnings. No gaps remain for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100% (baseline 3). Description adds value beyond schema by explaining that section_index should be obtained from get_article_outline, and providing detailed rationale for format parameter choices and limitations (round-trip safety, lossiness).

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

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

The description clearly states the tool retrieves content of a single section of an article in a given locale. It uses specific verbs ('Retrieve') and resources ('content of a single section of an article'), and distinguishes from siblings like get_article_outline and update_article_section.

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 advises to use get_article_outline first to discover section indexes. Provides clear when-to-use guidance for format parameter: 'html' for round-trip safety, 'markdown' only for human review, with explicit warning against round-tripping markdown content back through 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, and destructiveHint as false, covering safety. The description adds no further behavioral context beyond confirming it retrieves a user. No contradiction.

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

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

Two succinct sentences with no wasted words. Every sentence serves a purpose: stating the action and suggesting a use case.

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-only tool with rich annotations, the description is complete enough. It could optionally mention the return value structure, but the lack of output schema and simple nature make this sufficient.

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

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

No parameters exist, and schema coverage is 100%. The description does not need to add parameter details. Baseline of 4 is appropriate.

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

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

The description clearly states the tool retrieves the currently authenticated Zendesk user, using a specific verb and resource. It distinguishes itself from sibling tools like get_user which require a user ID.

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

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

The description mentions it is 'useful to verify identity and permissions,' providing clear context for when to use. However, it does not explicitly exclude any scenarios or mention alternatives, but for a zero-parameter tool this is adequate.

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. Description adds the behavioral context of listing incidents (not modifying), and the blast radius usage, which is valuable beyond annotations. No contradiction.

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

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

Two sentences, no wasted words. First sentence states the core function; second provides usage rationale. Perfectly front-loaded.

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

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

Given simple input (single integer) and rich annotations, the description provides adequate context. Does not describe the return format, but without an output schema and for a list-returning tool, agents can infer structure. A brief mention of the expected return type would improve completeness.

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

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

Schema coverage is 100% for the single parameter 'problem_id' with a detailed description. The description adds value by suggesting where to obtain the ID ('from search_tickets or list_tickets'), which is not in the schema.

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

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

Description clearly states the action ('Get all incident tickets linked to a problem ticket'), identifies the resource (incident tickets linked to a problem), and distinguishes from siblings like list_tickets by specifying the problem-incident relationship.

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 tool is useful 'before resolving a problem' to 'gauge a problem's blast radius'. This provides clear context for when to use. Does not explicitly mention when not to use, but the specific phrasing implies exclusive use for linked incidents.

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. The description adds behavioral context by specifying the richer return fields, complementing the annotations without contradiction.

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

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

The description is two sentences with no wasted words: first sentence states purpose and output, second provides usage guidance. Front-loaded and efficient.

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

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

For a simple 1-parameter tool with no output schema and good annotations, the description covers purpose, usage, and output detail. Could mention error cases, but overall complete enough.

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

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

Schema coverage is 100% and the schema's parameter description is thorough. The description does not add additional parameter semantics beyond what the schema provides, meeting the baseline of 3.

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

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

The description clearly states the tool retrieves a single organization by numeric id and returns full details (name, tags, domains, notes), explicitly distinguishing it from siblings like search and list_organizations that surface only name/id.

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

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

The description explicitly advises to use list_organizations for browsing or name-based lookup, establishing clear context for when to use this tool versus 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?

The description discloses that SLA may be absent for very high-volume requesters or just-updated tickets, and that comments are cut at the response character limit if present. It also clarifies that the SLA block is resolved via a scoped search, not directly from the ticket endpoint. These details go beyond the readOnlyHint and openWorldHint annotations, making the tool's limitations transparent.

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

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

The description is well-structured and front-loaded: the first sentence states the core action, then it details SLA behavior, comment inclusion, and alternatives. While lengthy, each clause serves a purpose (clarifying edge cases, redirecting to siblings) and there is no superfluous content. The logical flow from core function to caveats to related tools is clear.

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

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

The description provides complete context for correct usage: it explains what the tool returns, when SLA may be missing, how comment inclusion works and its truncation risk, and directs users to the appropriate sibling tools for history (get_ticket_history) and paginated comments (list_ticket_comments). It also notes the source of ticket IDs (search_tickets or list_tickets), giving the agent everything needed to decide when and how to invoke 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?

The input schema already provides thorough descriptions for both ticket_id and include_comments, including how to obtain the ID and the pagination caveat for comments. The tool description adds no new parameter-specific information beyond what is already in the schema, so it does not meaningfully enhance 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?

The description clearly states the tool retrieves a Zendesk ticket by ID and explicitly lists the returned fields (subject, status, priority, assignee, tags, description) plus optional comments and SLA state. It distinguishes itself from siblings by noting that SLA is resolved via a scoped search (list_sla_policies) and that comments are unpaginated, steering users to list_ticket_comments for long threads and to get_ticket_history for change history.

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

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

The description gives explicit when-to-use guidance: it explains that include_comments should be enabled only when the conversation is needed and defaults to false to keep the payload small. It further advises using list_ticket_comments for long threads because this tool appends a single unpaginated block that may be truncated, and get_ticket_history for historical changes. These alternatives are clearly named and conditions 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?

The description reveals an important behavior: images are embedded inline while other files are listed as text references. This goes beyond the readOnly and idempotent annotations, giving the agent insight into the response format. However, it does not cover potential error conditions, rate limits, or pagination, so it is not fully transparent.

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

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

The description is concise and front-loaded, with the core action stated in the first sentence. The second sentence adds essential detail without fluff. It avoids unnecessary words and is well-structured for quick understanding.

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

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

The description, combined with the schema, provides sufficient context for an agent to invoke the tool correctly. The action is clear, parameters are fully described, and the output format is partially explained. Minor gaps remain, such as the exact meaning of 'text references' and any pagination or error handling, but these are not critical for basic usage.

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 parameter descriptions in the schema are comprehensive (100% coverage), explaining the purpose and origin of each parameter, including the behavior when attachment_ids is omitted. The tool description adds no additional semantic meaning to the parameters, so the baseline score of 3 applies.

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

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

The description states the specific action 'Retrieve ticket attachments' with a clear verb and resource, and adds detail about the output format (images vs. text references). It is immediately obvious what this tool does, and it is distinct from sibling tools that focus on tickets, comments, or searches.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. It does not mention scenarios where this should be preferred over get_ticket or list_ticket_comments, nor does it specify conditions that would make it unsuitable. The only implicit hint is the focus on attachments, but this is not explicit enough for an agent to make a selection decision.

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, the description discloses oldest-first ordering, resolution of assignee/requester/group ids to names, comment presence markers, filtering of system-generated notification events, and that updates containing only such events produce no entry. This is rich behavioral context that annotations cannot convey.

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

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

The description is front-loaded with the core purpose and every sentence carries useful behavioral, filtering, or usage detail. It is relatively long and repeats 'oldest-first' a few times, but the tool's filtering and pagination behavior justify the length.

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 explaining return semantics, and it does: entry structure, actor/channel/field changes, comment markers, system-event filtering, pagination, and ordering. It also tells the agent where to obtain ticket_id (search_tickets or list_tickets), so nothing needed to select and 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 coverage is 100%, so the baseline is 3. The description mostly restates cursor and page_size semantics already present in the schema (oldest-first, dropped audits) and adds no substantial new parameter meaning beyond the phrase 'long-lived ticket'.

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

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

The description opens with a specific verb and resource: 'Read a ticket's change history — its audit trail — as a chronological, oldest-first timeline.' It also distinguishes itself from sibling tools by explicitly stating comments appear only as presence markers and pointing to list_ticket_comments or get_ticket for comment bodies, so an agent knows exactly what this tool does and what it does not.

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 concrete questions the tool answers ('what happened on this ticket?', 'why was it reassigned?', 'when did it go to pending?') and gives explicit alternatives: 'fetch the bodies with list_ticket_comments (or get_ticket(include_comments=true) for a short thread).' It also flags the filtered-event behavior so an agent won't expect a raw audit log.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it returns the full user record (name, email, role, etc.) and explains how to obtain the user_id (from search_users or ticket fields), which is useful context beyond 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?

Two sentences, no fluff, key information front-loaded. Every sentence adds value.

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

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

For a simple 1-parameter read operation with comprehensive annotations, the description covers everything: purpose, input, return fields, and id sourcing. No gaps.

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

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

Schema description coverage is 100% with detailed description for user_id. The description reiterates 'numeric id' and adds context on obtaining it, but doesn't add significant new semantic meaning beyond the schema.

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

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

The description explicitly states 'Retrieve a single user by their numeric id', specifying the verb and resource. It distinguishes from siblings search_users and get_current_user.

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 clear when-to-use (numeric id) and when-not-to (search_users for name/email, get_current_user for authenticated identity), with explicit 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 indicate readOnlyHint, idempotentHint, openWorldHint, and no destructive action. The description adds value by detailing pagination with cursor, the lack of live SLA block, and the return format matching list_tickets. No contradictions with annotations.

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

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

The description is a single, dense paragraph, but every sentence adds value. It could be slightly more structured (e.g., bullet points for parameters), but is efficient and front-loaded with the key action.

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

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

Given 5 parameters, no output schema, and strong annotations, the description covers all essential aspects: how to specify view, pagination, sort override, error handling, and limitations. No apparent gaps.

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%, but the description enriches each parameter: explains the anyOf for view, case-insensitivity and fallback behavior; cursor refers to previous response; sort_by enumerates examples and non-sortable fields; sort_order clarifies dependency on sort_by. Adds meaningful context beyond schema.

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

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

The description clearly states the main purpose: 'Read the tickets inside a Zendesk view' and emphasizes the view's own sort order. It distinguishes from sibling tools like search_tickets and list_tickets by noting the absence of SLA state and the use of view-specific ordering.

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 explicit guidance: use search_tickets for per-ticket SLA state, and explains how sort_by/sort_order can override the view's order. Also describes how to specify the view by title or id, and the case-insensitive matching with error recovery via returned titles.

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 indicate readOnlyHint=true, destructiveHint=false. The description adds that only metadata is returned (not file bytes) and that both inline and block attachments are included, which goes beyond the 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?

Three sentences efficiently convey purpose, return type, scope, alternatives, and related actions. Front-loaded with the core action, no extraneous words.

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

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

For a simple read-only list tool, the description fully explains what is returned (attachment metadata fields), the scope (both inline and block), and provides usage context via sibling distinction and upload reference. Annotations cover safety, and the output format is described despite no output schema.

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

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

Schema coverage is 100% for the single parameter article_id, with a clear schema description. The description does not add new information about the parameter beyond confirming it's for Help Center articles, meeting the baseline of 3.

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

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

The description clearly states 'List all attachments for an article' and specifies that it returns metadata (id, file name, content type, size, URL). It also distinguishes from get_ticket_attachments, which is a sibling tool.

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

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

The description explicitly says 'This is for Help Center articles — for attachments on support tickets use get_ticket_attachments instead' and mentions 'Upload new files with create_article_attachment', providing clear when-to-use and when-not-to-use guidance.

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

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

Discloses that it returns metadata only, that include_translations causes extra API calls, and pagination requirement. Adds value beyond readOnly and idempotent 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?

Two concise sentences plus a note. Front-loaded with purpose, no filler. Every sentence provides value.

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

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

Covers purpose, parameters, pagination behavior, and performance cost. Lacks explicit mention that results are paginated (but schema has cursor). Adequate for the complexity.

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

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

Schema coverage is 100%, so baseline 3. Description adds useful context like filtering options and sort_by values, and the performance note for include_translations. Exceeds baseline slightly.

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?

Clearly states it lists articles with metadata only, distinguishes from get_article for full content. Specific verb+resource+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?

Explicitly mentions using get_article for full content and notes include_translations must be re-sent on pagination. Could be more explicit about when not to use, but adequate.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, establishing a safe, read-only, and repeatable call. The description adds that only metadata is returned (no body), which supplements the annotations without contradiction.

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

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

Two sentences with no wasted words. The first sentence states the action and scope, the second provides a direct pointer to an alternative. Perfectly front-loaded.

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

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

Given the annotations (readOnly, openWorld, idempotent) and high schema coverage, the description is complete: it specifies what is returned (metadata fields), how to get full content, and where to obtain the required parameter. No output schema exists, but the description sufficiently describes the response shape.

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

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

The schema already provides a full description for article_id, including how to obtain it (from list_articles or search_articles). This adds context beyond the schema's basic type and constraints, improving usability.

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

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

The description clearly states it lists available translations for an article, specifies included metadata fields (locale, title, draft, updated_at), and distinguishes itself from get_article for full content. The verb 'list' and resource 'article translations' are specific and unambiguous.

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

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

The description advises using get_article with locale for full translated content, providing clear guidance on when to use this tool vs. the alternative. It effectively tells the agent to use this for metadata-only retrieval.

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 and non-destructive behavior; the description adds useful context about cursor-pagination and result structure (id, name, locale), enhancing transparency beyond annotations.

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

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

The description is concise, with three short sentences. The main action is front-loaded, and each sentence provides necessary information without 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 list tool with three optional parameters and no output schema, the description explains pagination, result fields, and integration with other tools. Slight lack of specification on ordering, but overall complete enough.

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

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

All parameters are fully described in the schema (100% coverage). The description mentions locale and pagination cursor but adds no new semantic meaning beyond the schema descriptions.

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

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

The description clearly states the tool lists all Help Center categories and explains the hierarchy (category -> section -> article), distinguishing it from sibling tools like list_sections and 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?

Provides clear context on when to use (top-level listing) and how to drill down using category id with list_sections and list_articles. Does not explicitly state when not to use but implicitly guides towards alternatives.

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

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

Annotations already declare readOnlyHint and destructiveHint, but the description adds critical behavioral context beyond annotations: it explains the subtle draft-versus-published distinction and how list_categories can mislead (omitting untranslated categories or listing draft names). This enriches the agent's understanding of what the tool reveals.

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

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

The description is front-loaded with the core purpose, then provides usage rationale and alternatives, with every sentence contributing value. Though longer than typical, the complexity of the draft/published pitfall justifies the length. No wasted words.

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

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

Given the tool's moderate complexity and lack of output schema, the description adequately explains returned fields, the key behavioral nuance, and how it fits with siblings. The agent has all necessary context 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% for the single parameter category_id, including how to obtain it. The description adds no additional parameter detail, so it neither helps nor hurts. Baseline 3 is appropriate since the schema already carries the full parameter burden.

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

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

The description clearly states the tool's function: 'List the translations of a Help Center category' and specifies the exact output attributes (localized name, description set, published/draft). It explicitly contrasts with sibling tools like list_categories and find_translation_gaps, making the purpose distinct and 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?

Provides explicit guidance on when to use this tool: 'Reach for this when a category looks wrong in a locale' and explains why list_categories is insufficient. It also names alternatives and follow-ups: 'Fix either case with set_category_translation; to sweep every category and section at once, use find_translation_gaps.' This fully covers when/when-not/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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds details: cursor-based pagination, default sort by name, page size cap of 30, and prefix-match behavior for name_prefix. No contradictions.

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

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

Two sentences, front-loaded with purpose, and no wasted words. Every phrase adds value.

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

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

Given the read-only nature, full schema coverage, and rich annotations, the description covers all necessary context: pagination, sorting, prefix search, and relationship to creation. No output schema needed.

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

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

Schema coverage is 100% with all parameters described. The description adds context for name_prefix: 'use the full name to check whether a specific tag already exists before creating it', which enhances parameter semantics beyond the schema.

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

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

The description clearly identifies the tool as listing 'Guide content tags' and defines them as 'end-user-visible labels that help readers find related articles'. It also distinguishes from sibling tool 'list_labels' by contrasting with internal labels.

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

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

The description provides explicit guidance: use name_prefix to check for existing tags before creating to avoid taxonomy fragmentation, and references list_labels for internal labels. It also specifies cursor pagination for full enumeration.

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. The description adds valuable context that labels improve search ranking and are not visible to end users, which helps the agent understand the domain and why listing labels is useful. No behavioral traits are missing beyond what annotations cover.

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

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

Two sentences, zero wasted words. The description is front-loaded with the core action and immediately provides relevant context. Every sentence serves a purpose.

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

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

The tool is simple with no parameters and no output schema. The description explains the domain of labels but does not describe the return format (e.g., what fields each label object contains). Since no output schema exists, the description should ideally clarify the output structure. It is partially complete but lacks this 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?

There are no parameters, so schema coverage is trivially 100%. The description adds meaning by explaining the nature of labels, which is indirectly related to the output. Per baseline for zero parameters, a score of 4 is appropriate.

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

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

The description clearly states 'List all article labels' with a specific verb and resource. It distinguishes this tool from siblings by focusing on 'article labels' specifically, even though there is a separate list_content_tags tool. The additional context about labels improving search ranking and not being visible to end users adds specificity.

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

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

The description provides no guidance on when to use this tool versus alternatives like list_content_tags. It does not specify prerequisites, use cases, or when not to use it. The agent is left to infer usage from the tool name 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 declare readOnlyHint and idempotentHint. The description adds value by specifying offset pagination details, per-user OAuth scope, and that no shared admin key is needed. It also describes the returned structure (id, title, etc.), providing context beyond annotations.

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

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

The description is informative with 4-5 sentences, front-loaded with the main purpose. Each sentence adds value (purpose, definition, return fields, usage hint). Could be slightly more concise, but structure is clear.

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

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

Despite no output schema, the description fully explains return fields and pagination. Parameters are covered by schema. The tool is used to list macros, with clear context for follow-up (preview_macro_diff). Complete for a list operation.

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

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

With 100% schema coverage, both parameters (page, per_page) are well-described in the schema with defaults and constraints. The description mentions offset pagination but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it 'List the active macros available to the authenticated user' and specifies the returned fields (id, title, description, scope, actions) with offset pagination. This specific verb-resource combination distinguishes it from siblings like preview_macro_diff.

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

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

The description implies usage context: to list macros as a precursor to preview_macro_diff by stating 'Pass a macro id from here to preview_macro_diff'. It also notes OAuth scoping. However, no explicit when-not-to-use or alternative tools are mentioned, though siblings provide coverage.

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, openWorldHint, idempotentHint, destructiveHint. The description adds pagination behavior (cursor-based) and return fields (name, id, basic fields), which is helpful but not exhaustive.

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

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

Four sentences front-load the main action, each sentence serves a purpose (pagination, returns, alternatives, use cases). No wasted words.

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

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

For a list tool with 2 parameters and good annotations, the description covers pagination, return contents, and usage context. No output schema but enough detail for agent to understand results.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context like 'omit for the first page' for cursor, adding value beyond schema.

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

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

The description states 'List all organizations with pagination' with specific verb and resource, and distinguishes from siblings get_organization and search by mentioning their different purposes.

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 when to use alternatives: 'Use get_organization with an id for full details' and 'search for query-based lookups by name', also provides context for usage in ticket creation/filtering.

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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it lists 'all' groups and returns permission_group_id, which is helpful context. No contradictions.

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

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

Two concise sentences, no waste. Front-loaded with purpose.

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

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

Complete for a parameterless list tool with good annotations. Output usage is specified.

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

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

No parameters; schema coverage 100%. Description adds no parameter info but none needed. Baseline applies.

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

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

The description clearly states the tool lists all Guide permission groups and connects it to the use case of finding permission_group_id for creating articles. This distinguishes it from sibling list 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 states when to use: to find permission_group_id for article creation. No exclusion criteria needed for such a simple tool.

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

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

Beyond the annotations, the description reveals significant behavioral traits: it scans article pages via multiple API requests, is uncached, potentially costly, may omit promoted articles on large Help Centers, and flags omissions and page count in the output. No contradictions with 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?

Though longer than typical, every sentence adds essential information: purpose, metadata-only return, cost caveat, uncached behavior, omission flags, locale scope, and modification alternative. The 'COST:' label structures the warning effectively, and the core purpose 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?

Without an output schema, the description clarifies that only metadata is returned and that omission/page-count flags appear in the output. It covers locale and modification alternatives, but does not enumerate specific metadata fields, which is a minor gap for a list 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?

The tool has zero parameters, so the empty schema fully defines the input surface. Since there are no parameters, the description cannot add parameter-level semantics; the baseline of 4 for 0-param tools is appropriate.

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

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

The description opens with a specific verb ('List') and a precisely scoped resource ('promoted Help Center articles'), further clarifying them as the curated set surfaced at the top of sections. It also distinguishes from siblings by directing to get_article for full content and update_article for modifications.

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 this tool vs alternatives: use get_article for full content, use update_article with `promoted` to modify promotion status. It also provides practical guidance on cost and repeated calls, advising against frequent invocation on large Help Centers.

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, openWorldHint, idempotentHint, destructiveHint. Description adds cursor-based pagination and typical fields returned, providing useful behavioral context beyond 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?

Four sentences, front-loaded with purpose. Each sentence adds unique value (purpose, hierarchy, pagination, parameter usage). No redundant or extraneous text.

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 list tool with no output schema, description adequately explains what is returned, how pagination works, and how parameters connect to sibling tools. Sufficient for correct invocation.

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

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

Schema coverage is 100% with descriptions. Description adds value by explaining that category_id comes from list_categories and that section id feeds into list_articles, enhancing understanding 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?

Clearly states 'List Help Center sections' and explains the hierarchy (category → section → article). Specifies fields returned (id, name, category_id, locale). Distinguishes from siblings like list_categories and 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?

Provides explicit context on when to use: pass category_id to filter by category, then use section id with list_articles. Mentions locale for translations. Could be more explicit about when not to use, but adequate.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds crucial behavioral context: it returns per-locale flags for description and published status, and clarifies the subtle draft-vs-missing distinction that list_sections cannot reveal. No contradictions with annotations.

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

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

The first sentence is concise and front-loaded. The second sentence is long but packed with necessary edge-case reasoning and alternative tool guidance. No filler, but the density could be slightly trimmed without losing value.

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

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

Given no output schema, the description fully covers what the tool returns (for each locale: name, description-set flag, published/draft) and how to interpret it. It also covers edge cases and corrective actions, making it contextually complete for a list operation.

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

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

Schema description coverage is 100%; the only parameter (section_id) is fully documented with its type, source, and how to obtain it. The description adds no additional parameter semantics, which matches the baseline of 3 for high schema coverage.

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

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

The description clearly states that the tool lists translations of a Help Center section with details per locale (localized name, description set?, published/draft). It also distinguishes itself from list_sections and other related translation tools, making its purpose unambiguous.

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

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

It explicitly says when to use the tool ('when a section looks wrong in a locale'), explains why the alternative list_sections is insufficient, and points to set_section_translation and find_translation_gaps for related actions. This is exemplary usage guidance.

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

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

Description adds critical behavioral info beyond annotations: the authentication requirement (admin vs agent) and that standard agents get 403. Annotations already indicate read-only/idempotent, so no contradictions.

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 concise sentences with front-loaded purpose. Every sentence adds value: purpose, use case, and permissions. No redundant or missing 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 purpose, use case, and permissions. Could benefit from explicitly stating it returns an array of policy objects, but the description's high-level overview is sufficient for selection.

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

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

Schema coverage is 100% with well-described pagination params. Description adds no extra parameter-level detail beyond 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?

Description clearly states the tool lists SLA policies with filter conditions and per-priority targets. It distinguishes from siblings like get_ticket (per-ticket SLA) by specifying it retrieves the policy configuration itself.

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 (reconstruct deadlines deterministically) and when not to (use get_ticket/search_tickets for per-ticket SLA). Also specifies required permissions (admin token) and notes alternatives for standard agents.

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 and idempotent, and the description adds behavioral details: cursor-based pagination, default small page size due to response character limits, and what the response contains (comment id, author, timestamp, public/internal flag, attached file ids). This goes beyond annotations to disclose runtime 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?

The description is dense but well-structured, using semicolons and explicit cross-references. Every sentence adds value—no fluff or repetition. It efficiently packs purpose, differentiation, pagination, and parameter guidance into a few lines.

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

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

For a read-only list tool, the description covers the return content, pagination behavior, sort order, and relationship to sibling tools. It addresses the likely questions an agent would have (how to get ticket_id, when to use alternatives) and aligns with the openWorldHint annotation.

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

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

The schema covers all parameters with descriptions, and the tool description augments them: ticket_id source (search_tickets/list_tickets), sort_order semantics (desc starts at newest, asc replays forward), and page_size rationale (deliberately small to avoid truncation). This gives full parameter context beyond the schema.

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

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

The description clearly states the tool reads a ticket's conversation, specifying the resource (ticket) and the action (list comments). It explicitly differentiates from get_ticket, get_ticket_history, and get_ticket_attachments, making its niche unambiguous for an agent.

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 explicit usage guidance: prefer this over get_ticket for long threads or when only needing latest exchange, and directs to get_ticket_history for audit trails and get_ticket_attachments for file downloads. It also explains how to use sort_order and cursor for pagination.

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 tool as read-only, idempotent, and non-destructive. The description adds valuable context: it returns specific fields, mentions cursor pagination, and notes that option values are provided for dropdown/multiselect fields. There is no contradiction with annotations.

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

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

The description is concise, with only four sentences that are all informative. It front-loads the action ('List the ticket field definitions') and each sentence adds distinct value: scope, return details, use case, and pagination info. No superfluous text.

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 read-only list tool with no output schema, the description adequately covers what the tool returns and why it's useful. It does not discuss error handling or rate limits, but the annotations cover safety. Given the tool's simplicity, 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 description coverage is 100%, so the schema already documents both parameters (cursor and page_size). The description mentions cursor pagination but adds no further details about parameter usage or constraints beyond what the schema provides. Thus baseline score of 3 is appropriate.

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

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

The description explicitly states it lists ticket field definitions (both system and custom fields) and details the returned fields (id, type, active/required, option values). This clearly distinguishes it from sibling list tools which list other entities like tickets or 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?

The description provides explicit guidance on when to use this tool: to discover field ids and option tags for create_ticket and update_ticket. It does not explicitly state when not to use it, but the purpose is clear enough that an agent would not misuse it. No alternative tool is needed as it's the only one listing field definitions.

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 value beyond annotations by detailing cursor-based pagination, page_size naming convention vs per_page in search_tickets, and ordering behavior (ascending id, not recency).

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

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

Two concise sentences, front-loaded with main action, no unnecessary words. Each sentence adds value.

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

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

Complete explanation for a simple list tool with two parameters, covers pagination, ordering, and comparison with sibling. No missing context.

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 already describes parameters well (100% coverage); description adds useful context about cursor usage and distinguishes page_size from per_page. Adds meaning beyond 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?

Clearly states verb 'List' and resource 'tickets', distinguishes default ordering (ascending id) and pagination method, differentiating it from search_tickets.

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 when to use this vs search_tickets: for ordering by recency or other criteria, use search_tickets. Also mentions default ordering and pagination specifics.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context that user segments control article visibility, which helps the agent understand the relevance of the data. No contradictions.

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

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

Two sentences, no wasted words. Essential information 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 simple, zero-parameter, read-only list tool, the description is complete. It explains the purpose and how the result is used. No output schema is needed.

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 no parameters, and schema coverage is 100%. Baseline is 3. The description does not add parameter-specific information, but none is needed.

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

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

The description clearly states it 'list all user segments' and explains that user segments control article visibility. This distinguishes it from other list tools that operate on different resources (articles, tickets, etc.).

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

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

The description says 'Use the ID when creating or updating articles,' which indicates the primary use case. It does not explicitly state when not to use it, but the context is clear enough.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds critical context about count staleness (up to an hour lag) and the '(count updating)' indicator, providing behavioral insights beyond 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?

Three sentences, front-loaded with purpose, and efficiently conveys key details without fluff. All sentences are informative and earn their 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, description explains that the tool returns views with ticket counts and notes caching behavior, which is sufficient for an agent to understand the tool's output and how to use it.

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% for the two parameters (cursor, page_size). Description does not add additional parameter semantics beyond what the schema already provides.

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

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

Description clearly specifies verb 'list' and resource 'Zendesk views', and distinguishes from sibling tools like get_view_tickets by mentioning that views are per-agent scoped and that counts are included. It also differentiates from list_tickets by focusing on views.

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?

Description explains that views are per-agent scoped and recommends using get_view_tickets to read tickets inside a view, giving context on when to use this tool vs. alternatives. However, it does not explicitly state when not to use it.

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

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

Annotations already indicate destuctiveHint=true, idempotentHint=true, openWorldHint=true. Description adds value by explaining the no-op behavior for redundant adds/removes, duplicate collapsing, and return of full tag set. No contradictions with 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?

Concise, front-loaded, and well-structured. Every sentence adds value: behavior, idempotency, return value, when to use alternatives, and how to find ticket id. No wasted words.

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

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

For a tool with 3 parameters and no output schema, the description fully explains behavior, edge cases (no-op), return value, and how to obtain required parameter. Complete and actionable.

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 parameter descriptions are already detailed. Description reinforces behavior but does not add significant new meaning beyond schema for individual parameters.

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?

Clearly states 'add or remove tags on a ticket' and explains the incremental read-modify-write behavior, distinguishing it from update_ticket which overwrites the entire tag set.

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 use this for incremental tag edits and directs to update_ticket for overwriting or changing alongside other fields. Also mentions how to obtain 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?

Annotations declare readOnlyHint=false, implying possible writes, but the description insists 'nothing is committed' and tool is read-only. This contradiction misleads agents about side effects.

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

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

Front-loaded with purpose, but multiple sentences could be slightly tighter. Still, every sentence adds value and 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?

No output schema exists, so description fully explains return format (only changed fields, omitted identity fields), prerequisites, and two-step workflow, making the tool self-contained.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context by explaining how to obtain macro_id and ticket_id, and that they are numeric IDs, exceeding schema documentation.

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 ('preview'), resource ('macro diff on a ticket'), and scope ('as a before → after diff, WITHOUT saving anything'), clearly distinguishing from sibling tools like update_ticket and add_comment.

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 (to preview changes before applying) and when not (nothing committed; must follow up with update_ticket and comment tools). Provides alternatives for obtaining macro IDs and ticket IDs via list_macros and search_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?

Discloses that it writes minimal positions, may reposition neighbors, detects automatic sorting, and requires confirmation for large reorders. This adds context beyond annotations which show idempotent and destructive hints.

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 sentences front-loaded with core action and purpose. Every sentence adds value, no wasted words.

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

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

Covers all aspects: reordering behavior, edge cases (automatic sorting), parameter details, return value, and safety mechanism. No output schema but description adequately states return value.

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

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

Schema has 100% coverage; description adds context like confirm threshold default (20) and that before/after require reference_article_id. Provides additional useful semantics beyond schema.

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

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

The description clearly states the tool reorders an article within its current section by moving it relative to siblings, with specific verbs and resource. It distinguishes from update_article for moving to different section.

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 provides when to use: for 'put first/last' requests, and when not: for moving to different section, directing to update_article. Also explains detection of automatic sorting and safety threshold.

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 mark it as read-only and idempotent. The description adds concrete behavioral details: paginated results at 100 per page, total count included, and organization results limited to name and ID. No contradictions with annotations.

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

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

The description is two sentences highly efficient: one for purpose and filtering, one for pagination and limitation. No filler words; every sentence adds value.

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

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

For a search tool with 3 parameters and no output schema, the description covers what is searched, how to filter, pagination behavior, and result limitations. Minor gap: does not mention the response format for tickets/users, but the schema and examples are sufficient.

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%. The description enhances semantics by providing example filter syntax, explaining how page and per_page work together for pagination, and noting the limitation of organization results. This goes beyond the schema's field descriptions.

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

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

The description clearly states that this tool searches across tickets, users, and organizations, with specific filter examples. It distinguishes itself from sibling tools like search_tickets, search_users, and search_articles which are scoped to single types.

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

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

The description explains when to use it (cross-object search) and provides an alternative for organization details (get_organization). It does not explicitly contrast with single-type searches but strongly implies through the unified nature.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds value by clarifying that only metadata (not body) is returned, and mentions return of 'total count'. No contradictions with annotations.

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

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

The description is a single, well-structured sentence that front-loads the core purpose. Every element earns its place with no fluff.

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

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

For a search tool with 4 parameters and no output schema, the description adequately covers scope (metadata only), return total count, and locale filtering. However, it does not describe the output structure or pagination behavior beyond what the schema covers, leaving some gaps.

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

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

Schema coverage is 100% with detailed descriptions for all 4 parameters. The description reinforces that 'query' is full-text and 'locale' filters, but does not add new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Full-text search across Help Center articles (metadata only, no body)' and distinguishes from 'get_article' for full content. It specifies the resource (Help Center articles) and the action (full-text search) with scope constraints.

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

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

The description explicitly directs to 'use get_article for full content' if needed, and notes 'Supports locale filtering.' However, it does not differentiate from sibling tools like 'list_articles' or 'search_tickets', missing some context on when to choose this over 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 declare readOnlyTrue and idempotentHint. Description adds important behavioral details: returns SLA state per ticket, total count, automatic addition of 'type:ticket' scope, and explains why 'type:' filter is not allowed. These go beyond what annotations 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?

Description is two sentences plus an example line. Every sentence adds value: first sentence states purpose and key feature, second gives examples, third explains total count benefit. No wasted words.

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

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

With 3 parameters fully described, no output schema, the description covers the return behavior (ticket data, SLA state, total count). It could mention relationship to get_ticket or list_tickets, but is still sufficiently complete for an agent to understand the tool's functionality.

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

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

Schema coverage is 100% with parameter descriptions. Description adds value by providing example queries, explaining the automatic 'type:ticket' addition, and clarifying pagination behavior. This helps the agent understand parameter usage beyond schema alone.

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

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

Description states it searches tickets using Zendesk query syntax, distinguishes from list_tickets (which likely returns all tickets) and get_ticket (single ticket). Mentions returning SLA state and total count, which adds specificity.

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

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

Provides examples of queries and explains benefit for queue triage. Does not explicitly contrast with sibling search tools, but context is clear enough for an agent to decide when to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's addition of 'Returns total count' is useful but minimal. It does not disclose details about rate limits, the meaning of openWorldHint, or the behavior of empty queries, but it does highlight the Zendesk query syntax, which informs the agent.

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

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

The description is two sentences, front-loading the primary purpose. Every sentence contributes meaningful information: what it searches (users), how (Zendesk query syntax), and what it returns (total count). There is no redundancy or wasted words.

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

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

The description is relatively complete given the tool's simplicity and the fact that the schema covers parameters and annotations cover safety. However, it omits that the tool returns a list of user objects (not just a count) and does not mention pagination behavior explicitly, which could be necessary for the agent to estimate page sizes and handle large results.

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

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

With 100% schema description coverage, the schema already explains the parameters. The description adds value by clarifying that the query supports free text and field filters, and by stating the return of total count (not in schema). However, it does not elaborate on pagination semantics or the exact response structure, 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?

The description clearly states it searches for users by name, email, or other criteria using Zendesk search query syntax. It explicitly identifies the resource (users) and the action (search), distinguishing it from sibling tools like search_tickets (tickets) or search (generic). The mention of returning total count adds concreteness.

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

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

The description implies usage when needing to search for users, but it does not explicitly state when to use this tool versus alternatives like get_user for a single user or the generic search tool for cross-object searches. No exclusions or comparisons are provided, leaving the agent to infer 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?

Beyond annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description reveals key upsert semantics ('Creates the translation when the locale has none and updates it otherwise'), partial field updates ('only the fields you pass are written'), and how to publish a draft ('draft: false'). No contradictions with 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?

Three sentences, front-loaded with core action in first sentence. The second and third sentences are dense but add critical behavior and usage context. Slightly long but 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?

With 5 parameters, no output schema, and annotations indicating a write/idempotent/destructive operation, the description covers the operation's behavior, return value, and use case. The schema already documents parameter constraints, so the description is complete for selecting and invoking the 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?

Input schema covers 100% of parameters with detailed descriptions (e.g., name requiring when no translation, draft defaults, locale active check). The description adds no additional parameter-level meaning beyond what 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?

Description uses specific verb 'Create or update' and identifies resource 'translation of a Help Center category in one locale'. It distinguishes from sibling tools like list_category_translations and find_translation_gaps by explaining the upsert behavior and return value.

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: 'to make a category reachable in a locale where its sections or articles are already translated'. It also mentions that find_translation_gaps reports the gap and list_categories cannot explain, providing context. However, it doesn't explicitly exclude using it for sections or name set_section_translation as alternative, so it's clear but not exhaustive.

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 annotations (readOnly=false, destructive=true, idempotent=true), the description discloses the upsert behavior (creates when absent, updates otherwise), partial-write semantics ('only the fields you pass are written'), and the use of draft:false to publish. It also specifies the return payload (locale, localized name, draft state), which is not already provided by 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?

The description is three sentences, front-loaded with the primary function, and every sentence delivers distinct value: purpose, operational detail, and use-case context. There is no fluff 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 tool with 5 parameters, no output schema, and moderate complexity (upsert plus draft states), the description covers the operation, scope, partial-update behavior, return value, and a concrete use case. It also differentiates from related sibling tools sufficiently.

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

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

Schema description coverage is 100%, so this is a baseline 3. However, the tool description adds strategic context beyond the schema by explaining how parameters interact, such as 'only the fields you pass are written' and 'publish this draft' being a single draft:false call. This helps agents understand parameter semantics in context, though most details are already in the schema.

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

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

The description begins with a specific verb phrase 'Create or update' and clearly identifies the resource: 'the translation of a Help Center section in one locale'. It also distinguishes the tool from siblings by referencing find_translation_gaps and list_sections, clarifying its unique role.

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

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

The description provides explicit when-to-use guidance: 'Use it to make a section reachable in a locale where its articles are already translated — a gap find_translation_gaps reports and list_sections cannot explain.' It also states that no listing call is needed first, implying when not to use list_section_translations as a precursor.

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 provide readOnlyHint=false, destructiveHint=true, etc. The description adds context that the tool returns the updated article and does NOT update content (title, body). This is helpful but not extensive beyond 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?

Two sentences, front-loaded with the core purpose, and every sentence adds value. No wasted words.

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

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

Given the tool's complexity (10 parameters, no output schema), the description is complete enough. It covers the scope, return value, and exclusions, sufficient for an agent to use correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds very little extra meaning beyond stating the return value. 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?

The description clearly states the verb 'Update' and specifies the resource 'article metadata only'. It distinguishes from the sibling tool update_article_translation by excluding content updates, which removes 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?

The description explicitly states when to use this tool (for metadata updates) and when not to (for content updates, use update_article_translation). This provides clear guidance and 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?

Discloses that the section heading is preserved and not part of replaced content, the default format choice for fidelity, and the server-side reconstruction. Annotations already indicate destructive and idempotent behavior; description adds valuable context without contradiction.

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

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

The description is concise, with no wasted words. It front-loads the main action and includes important details in a logical order. Every sentence contributes value.

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

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

Given no output schema, the description adequately covers the tool's behavior and parameter usage. It explains the replacement process and format caveats. A brief note on return values (e.g., updated article) would improve completeness, but the current description is sufficient for an agent.

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

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

Schema coverage is 100%, so the description's parameter details are supplementary. It explains the purpose of section_index (0-based from get_article_outline) and the implications of the format parameter, adding meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Replace the content of a single section of an article in a given locale, keeping the rest of the body intact.' It specifies the verb, resource, and scope, and distinguishes it from sibling tools like update_article_translation or reorder_article.

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 explicit guidance on when to use 'html' vs 'markdown' formats, including a warning about round-trip issues. It explains the server-side process. However, it could mention prerequisites like calling get_article_outline to obtain section_index.

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, so the bar is lowered. The description adds behavioral context by stating that the tool 'replaces the FULL body and re-sends the entire article on each write,' which explains the destructive nature and re-sending 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?

The description is two sentences long, front-loading the purpose and then providing usage guidance and behavioral notes. Every sentence adds value with no redundancy or unnecessary detail.

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

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

Given the tool's complexity, rich annotations, and clear schema, the description covers all necessary context: when to use, what it does, how it differs from siblings, and a key behavior (full body replacement and re-sending). No gaps remain.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by contextualizing the locale parameter (use source_locale for default language) and contrasting body with the sibling tool, improving semantic understanding beyond the schema.

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

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

The description clearly states the tool updates article content (title, body) in a specific locale. It distinguishes itself from the sibling tool 'update_article_section' by specifying that this tool replaces the full body, making the purpose highly specific and unambiguous.

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

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

The description explicitly advises when to use alternatives: 'For targeted edits on one or a few sections, prefer update_article_section.' It also explains how to handle the default language using source_locale, providing clear context for correct invocation.

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

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

The description discloses that only passed fields are changed, tags replace the whole set, and the tool does not post replies. Annotations (destructiveHint, idempotentHint) are consistent, and the description adds useful behavioral context beyond the annotations.

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

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

The description is concise with three well-structured sentences. It front-loads the key information (what the tool does and its parameters) and efficiently adds usage guidelines and behavioral notes without 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?

Despite 9 parameters and no output schema, the description covers essential aspects: partial update behavior, tag replacement, no replies, and how to find the ticket_id. It provides enough context for an agent to use the tool effectively.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that setting tags replaces the entire set (reinforcing the schema), that only specified fields are changed, and that the updated ticket is returned. It also provides guidance on how to obtain the ticket_id, which aids in parameter selection.

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

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

The description explicitly states 'Update an existing ticket' and lists the fields that can be updated (status, priority, type, etc.). It distinguishes the tool from siblings like add_public_comment, add_private_note, and manage_tags, making the purpose clear and specific.

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

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

The description provides clear guidance on when to use alternatives: 'use manage_tags to add or remove individual tags' and 'use add_public_comment or add_private_note for replies'. It also explains how to obtain the ticket_id via search_tickets or list_tickets, helping the agent decide when to invoke this tool.

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