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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's job is to add semantics beyond mutability, which it does: visibility (internal, agent-only), append semantics ('appended to the ticket thread'), and the attachment delivery path via the Zendesk Uploads API. It does not address what happens on repeated calls (non-idempotent, so duplicates append) or failure behavior for oversized uploads, leaving a small gap.

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

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

Two sentences with no filler; the core behavior and requester-visibility constraint come first, and the alternative-tool routing comes second. Every clause earns its place.

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

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

For a 3-parameter mutation tool with a fully documented schema and no output schema, the description covers purpose, visibility, threading behavior, attachment handling, and the sibling alternative. It stops short of describing the response (e.g., whether the created note or attachment references are returned), which matters slightly given there is no output schema.

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

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

Schema description coverage is 100%, so the schema already carries markdown/HTML rendering rules, ticket_id sourcing, and attachment size limits. The description adds only that attachments are uploaded via the Uploads API and carried on the note, which is useful framing but not new per-parameter meaning. Baseline 3 applies.

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

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

States a specific verb and resource ('Add an internal note ... to a ticket') plus the critical scope detail that it is not visible to the requester. It explicitly distinguishes itself from add_public_comment, so an agent can route between the two without opening either schema.

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

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

Names the alternative tool (add_public_comment) and the exact condition that selects it ('when the reply should be visible to the requester'). This is an explicit when/when-not rule rather than implied usage.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's real contribution is the undisclosed side effect: posting emails the requester and appends to the ticket thread. It also explains the attachment pipeline (Uploads API, carried on the comment), which no annotation conveys. It stops short of noting irreversibility (no edit/delete path mentioned) or any rate/size caveats beyond the schema.

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

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

Two sentences, zero filler, with the visibility constraint and the email side effect front-loaded before the sibling routing advice. Every clause carries decision-relevant information.

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

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

For a write tool with rich schema and solid annotation coverage, the description supplies the missing behavioral piece (requester email, thread append) and the key sibling choice. It does not describe the response shape, but the operation is simple enough that this is a minor gap.

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

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

Schema description coverage is 100%, so body, ticket_id, and the attachment fields are already fully documented, including Markdown/HTML rendering rules and size caps. The description adds only that attachments are uploaded via the Zendesk Uploads API and carried on the comment, which is modest mechanism context beyond the schema, so the baseline of 3 is appropriate.

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

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

The description gives a specific verb and resource ("Add a public comment ... to a ticket"), states the audience ("visible to requester"), and explicitly distinguishes itself from the sibling add_private_note. An agent can pick between the two comment tools without opening either schema.

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

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

It names the concrete alternative (add_private_note) and the exact condition that selects it (internal, agent-only note), which is the primary fork an agent faces here. The requester-visible/emails-the-requester framing further reinforces when this tool is appropriate.

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

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

Goes well beyond the annotations: it discloses the non-obvious side effect that replying to a solved request REOPENS it, that comments are always public because end users cannot post internal notes and private flags are silently ignored, and that a closed request rejects comments outright. These are exactly the behavioral traits an agent could not infer from readOnlyHint/destructiveHint/idempotentHint.

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

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

Front-loads purpose, then conventions, then alternatives, so an agent gets the essentials in the first clause. A few phrases are rhetorically padded ('which matters because', 'the user should know that is what their message did') though they do carry meaning about user-facing consequences.

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 mutating, attachment-bearing tool with no output schema, the description covers the return value (confirmation with the request's status), side effects, and a failure mode. It gives the agent everything needed to call it correctly and to anticipate the consequence.

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 parameters are already documented, including plain-text body rendering and base64 attachment limits. The description adds only that files are optionally attached to the reply, which is largely a restatement of the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource — 'Reply on one of the signed-in user's own requests' — and scopes it to the caller's own requests, with optional file attachments. It is immediately distinguishable from the named siblings add_public_comment and add_private_note.

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

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

Explicitly routes the agent: agents replying to a requester should use add_public_comment, and internal notes belong to add_private_note. It also names a condition under which the call is unnecessary or unsafe (a closed request rejects comments), leaving nothing to inference.

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

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

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

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

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

The destructive semantics are front-loaded in the first clause and each sentence carries useful information. There is mild redundancy with 'Guide admin UI' appearing in two separate sentences, but overall it is efficient and well-ordered.

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

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

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

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema itself, including the confirm safety guard. The description only echoes the guard ('Guarded by a required confirm flag') without adding syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Archive (soft-delete) a Help Center article') and immediately clarifies the semantics of the operation. It distinguishes itself from the sibling update_article by naming it explicitly as the non-destructive alternative.

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

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

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

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

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

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

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

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

Front-loaded with purpose followed by five numbered signals, so structure is legible. It is dense and long, but with no output schema nearly every sentence carries necessary return-value semantics, so the length is largely earned.

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

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

No output schema exists, and the description fully compensates by enumerating each returned signal (Freshness, outdated flag, structure check, per-section table, word counts) and their semantics. For a read-only comparison tool, nothing an agent needs to call and interpret it is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented with descriptions. The description consistently uses 'source' and 'target' but adds no format or constraint details beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb (compare) and resource (two locales of the same article) plus the decision it supports (whether the target translation needs work). An agent can distinguish this from siblings like find_translation_gaps or list_article_translations without opening a schema.

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

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

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

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

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

Beyond annotations, it discloses that nothing is written to Zendesk, that thresholds are per-server and per-user only, that they drive list_sla_alerts and the Urgency line of get_ticket/search_tickets, and that resetting the 'wait'/'reply'/'all' families has different downstream effects. It also documents the operator-disabled degradation path, which annotations cannot express.

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

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

The read-vs-write split is front-loaded in the first two sentences and every subsequent clause adds an operational fact. It is a single dense paragraph, though, and the reset/disabled-mode details could be split for easier scanning.

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

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

With no output schema, the description still tells the agent what a no-parameter call returns (thresholds in force plus their origin: user preference vs server default) and what the disabled-operator reply looks like. For a 5-parameter, zero-required, configuration tool that is complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value on top by defining the metric families (reply = first_reply_time/next_reply_time; wait = everything else) that the individual parameter descriptions only gesture at. It stops short of restating duration syntax or the warning/critical ordering constraint, which the schema already carries.

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

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

The description states a specific verb pair and resource: read or change your personal SLA alert thresholds (WARNING/CRITICAL proximity to breach). It clearly distinguishes itself from list_sla_alerts by describing the latter as a consumer of the stored thresholds, so an agent can tell read-and-write-config from the read-only alert listing.

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 spells out the two modes explicitly: no parameters = pure read, parameters = persist per-family thresholds, and reset = fall back to server defaults. It also gives the failure case (SLA_USER_PREFERENCES=off means only the read works and the response says so), which is exactly the kind of when-not guidance an agent needs.

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

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

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

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

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

Three compact sentences, front-loaded with the core action and return value, then the permission prerequisite, then the sibling handoff. No filler.

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

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

For an 11-parameter creation tool with no output schema, the description covers the key gaps an agent needs: the return value, the critical required permission_group_id, and the translation follow-up path. It leaves some behavioral detail (draft default behavior, author default) to the schema, which is acceptable given full schema coverage.

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

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

Schema description coverage is 100%, including usage hints like list_sections/list_labels/list_user_segments, so the schema carries parameter explanation. The description only reinforces permission_group_id and the locale↔source_locale relationship, adding marginal value over structured data.

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

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

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

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

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

Gives sequencing guidance: use list_permission_groups to obtain the required permission_group_id, and use create_article_translation afterwards for other locales. It does not state when-not-to-use this tool (e.g. for existing articles, where update_article applies), so it stops short of full routing.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, but the description adds the concrete consequence of non-idempotency ('uploads another copy rather than replacing'), which is actionable beyond the boolean. It also compensates for the absent output schema by enumerating the returned fields. It does not mention auth/permission requirements, so not a full 5.

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

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

Three sentences, front-loaded with the core action and return value, followed by the important non-idempotency caveat and sibling routing. No filler; every sentence earns its place.

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

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

For a write tool with no output schema, the description supplies what the schema cannot: the shape of the return value, the non-idempotency behavior, and disambiguation from related attachment tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including base64 encoding, size limits and MIME type. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (upload) and resource (file to a Help Center article), and explicitly describes the return payload. It distinguishes itself from siblings by naming both get_ticket_attachments and list_article_attachments, so an agent can tell it apart without opening other schemas.

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

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

Explicitly routes the agent: 'for files on support tickets use get_ticket_attachments' and 'to see an article's existing attachments use list_article_attachments.' Both the when-to-use and the alternatives are stated.

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

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

Annotations already declare the safety profile (not read-only, not idempotent, not destructive, open-world). The description adds meaningful context beyond them: the article-existence prerequisite, the no-existing-translation constraint (which effectively explains the non-idempotent behavior), and the return payload (locale, title, draft state). It does not mention permission/auth requirements, which is the remaining gap.

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

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

Front-loads the core action, then the prerequisites, the constraint with alternatives, and the input requirement. Every sentence carries distinct information with no repetition.

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

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

For a mutation tool with no output schema, the description covers the action, prerequisites, constraint, alternatives, required inputs, and even the shape of the returned translation. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description only reinforces the body requirement ('full HTML body') and the locale/draft concepts, adding marginal meaning over the structured fields. Baseline 3 is appropriate.

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

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

States a specific verb (create) and resource (article translation) scoped to a locale, and explicitly distinguishes itself from create_article (which creates the source article) and update_article_translation (which modifies an existing translation). An agent can route correctly without opening any schema.

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

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

Explicitly states the precondition (article must already exist, use create_article first), the constraint (target locale must not already have a translation), and names the two alternatives — update_article_translation for modifying and list_article_translations for discovering existing locales. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavior beyond that: it discloses the return payload ('returns the created tag with its id') and implies a non-idempotent duplicate risk by recommending a lookup first. Permission requirements and the consequence of duplicates are not stated, keeping it short of a 5.

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

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

Three tightly written sentences: purpose first, then what it returns and the duplicate-avoidance workflow, then the contrasting alternative. Every sentence carries distinct information with no repetition.

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

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

Despite having no output schema, the description states the return value ('the created tag with its id'), covers the create-then-attach lifecycle, and routes to the correct alternative for a closely related concept. Nothing needed to invoke it correctly is missing.

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

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

Only one parameter, and schema description coverage is 100% with a clear description and example values ('billing', 'getting-started'). The description's 'end-user visible labels' phrasing reinforces the schema rather than adding new syntax or constraint detail, so the baseline 3 for fully documented schema applies.

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

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

States a specific verb+resource ('Create a new content tag for Guide articles') and immediately defines what a content tag is and how it differs from article labels, a sibling concept (list_labels). An agent can distinguish it from manage_tags and list_content_tags without opening any schema.

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

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

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

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

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

Goes well past the annotations by disclosing the validation contract (unknown form id, missing required field, or unoffered dropdown value is refused client-side) and the reason: Zendesk answers 201 while silently substituting the default form, accepting an empty subject, or dropping unknown values. It also discloses that priority and type are silently dropped for end users, and that the return value is the created request including its number. The only gap is that it doesn't describe auth failure modes or rate limiting.

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

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

Front-loaded with purpose, then prerequisites, validation behavior, and the sibling alternative in a sensible order. A few clauses are redundant with the schema's own custom_fields text (the tag-string rule appears twice across description and schema), costing a point.

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 non-idempotent write tool with no output schema, the description covers the return value (created request plus number), the fabrication-failure modes, prerequisite discovery via get_request_form, and the correct alternative tool. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot: it warns that priority and type are not settable by an end user, ties form_id and custom_fields back to get_request_form/list_request_forms, and flags that submissions are validated rather than silently coerced. It does repeat the schema's own dropdown-tag-not-number rule, which keeps it from a 5.

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

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

States a specific verb and resource ("Submit a new support request as the signed-in user") and anchors it to the familiar Help Center form. It explicitly separates itself from the two nearest siblings: create_ticket (agent acting for someone else) and get_request/list_requests (follow-up reads).

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

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

Gives an explicit prerequisite ("Call get_request_form first to learn which fields to gather"), an explicit exclusion ("This posts as the authenticated user; an agent opening a ticket on someone else's behalf wants create_ticket instead"), and names the follow-up tools the user would use afterward.

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 (write, open-world, non-idempotent), the description discloses a real side effect: the description body becomes the first public comment visible to the requester, and markdown is rendered while HTML is not. That is valuable context an agent would otherwise miss. It stops short of stating who the requester becomes (no requester_id parameter exists) or any permission/auth requirements, which leaves a meaningful gap for a creation tool.

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

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

Four sentences, front-loaded with what is created and what is returned, followed by follow-up routing and lookup guidance. Every sentence carries information an agent needs; nothing is repeated from the schema or annotations.

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

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

With no output schema, the description compensates by stating the new ticket id is returned, and it covers side effects, follow-up tools and id-discovery for the non-obvious parameters. The one unresolved question for a creation tool is who the ticket is created for / whether the caller becomes the requester, which is not addressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds actionable meaning by pointing to search_users for assignee_id/group_id and to list_ticket_fields for custom field ids and accepted dropdown tags. It does not add anything about subject or priority beyond what the schema enums and descriptions already state.

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

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

The first sentence names a specific verb and resource ('Create a new Zendesk support ticket') and enumerates the fields it accepts (subject, description, optional priority/type/assignee/tags), so an agent can immediately separate it from read tools like get_ticket and from adjacent creators such as create_request or create_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?

It explicitly routes post-creation work to update_ticket, add_public_comment, add_private_note and manage_tags, and states prerequisites for the harder parameters (resolve assignee_id via search_users, discover custom field ids and accepted option values via list_ticket_fields). This is a complete when/when-next/where-to-look map rather than a vague hint.

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

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

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

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

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

Front-loads the purpose in the first sentence and keeps every clause information-bearing. The second sentence is a dense run-on with multiple em-dash clauses, which slightly hurts scannability, but no content is padding.

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

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

With no output schema, the description still tells the agent what the report contains (gaps plus the reason: missing vs unpublished draft) and its limits. Combined with the routing to fix tools, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the tradeoff of omitting category_id (full sweep costs two listings, capped at 100/100) versus passing it to narrow the audit, and notes the inactive-locale warning behavior for locale.

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

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

States a specific verb (audit), resource (Help Center tree for a target locale), and precisely what it reports: categories/sections with no translation or only an unpublished draft. It is unambiguously distinguishable from the listing siblings like list_sections/list_articles.

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

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

Explicitly says when to use it (before/after translating articles) with the concrete motivating scenario of an article being unreachable while its parent section only exists in the source locale. It names the alternative (listing sections in that locale) and explains why it fails, and routes fixes to set_section_translation / set_category_translation.

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

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

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

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

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

Four tight sentences, each earning its place: retrieval scope, routing alternative, locale option, return shape. It is front-loaded with the core action and contains no filler.

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

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

There is no output schema, yet the description enumerates the return contents (body HTML, metadata, source_locale, translations). Combined with complete parameter coverage and annotation-backed safety, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema (article_id even names its source tools). The description's note that locale fetches a translated version is a small addition but largely restates the schema's own 'Locale for translated version' text, so the baseline 3 applies.

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

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

States a specific verb (Retrieve) and resource (an article) and clarifies scope: 'by ID with full body content'. It explicitly distinguishes itself from the sibling tools get_article_outline and get_article_section, so an agent can route without opening any schema.

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

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

Names the alternative tools (get_article_outline + get_article_section) and the exact condition that selects them ('For large articles ... to save tokens'). This is explicit when-to-use/when-to-prefer-alternative guidance, not merely implied context.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavioral value beyond annotations: it discloses the return shape (h1/h2/h3 sections with word counts) and that translations with outdated status are bundled in — non-obvious extra content the agent should expect.

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

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

Two tight sentences with the primary behavior front-loaded and the sibling routing second. Every clause earns its place; nothing is padded.

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

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

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

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

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

Schema description coverage is 100%, and both params (article_id, locale) are documented in the schema. The description only restates the locale default that the schema already states, adding no syntax or format detail beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource ('Return a compact outline of an article') and details exactly what the outline contains — h1/h2/h3 sections with word counts plus translation/outdated status. An agent can distinguish it from get_article and get_article_section without opening a schema.

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

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

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

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

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

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

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

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

Front-loaded with the core purpose, then prerequisites, then format guidance. Every sentence carries information, though the middle format sentence is dense and could be trimmed slightly.

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning beyond the schema by explaining the risk profile of the markdown enum value and by documenting an undocumented aspect of the returned content (the label line at the top).

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

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

States a specific verb (Retrieve), resource (content of a single section of an article), and scope qualifiers (single section, given locale), which cleanly separates it from get_article and get_article_outline without ambiguity.

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, covering the safety and mutation profile. The description adds the scope that this returns the authenticated user and a use case, but says nothing about auth requirements, rate limits, or return shape. With annotations doing the heavy lifting, a 3 is appropriate.

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

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

Two short sentences, front-loaded with the core action and followed by a brief use case. No filler or repetition; every sentence earns its place.

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

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

For a simple, zero-parameter read tool with rich annotations and no output schema, the description gives the agent everything needed: what it retrieves, whose identity it targets, and why one would call it. No critical details are missing.

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

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

The tool takes zero parameters, so the rubric sets the baseline at 4. The schema is empty and the description introduces no additional parameter semantics, which is acceptable for a no-argument tool.

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

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

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

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

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

Provides a clear use case: 'Useful to verify identity and permissions.' This tells the agent when to reach for the tool, but it does not state when not to use it or name alternatives such as get_user, so it lacks exclusion guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real value beyond them: results are truncated to 200-character excerpts and get_ticket should be used for the full body — behavior an agent could not infer from the schema. Pagination/result limits are left unstated.

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

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

Three tight sentences: purpose first, then use case, then the truncation caveat with the escape hatch. Nothing is redundant and the most decision-relevant 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?

With no output schema, the description carries the burden of explaining returns, and it does: a list of incident tickets with truncated descriptions. It is missing any statement about result ordering, pagination, or how many links are returned, which matters for a potentially unbounded list.

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

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

Schema coverage is 100% and the schema already explains that problem_id is the numeric id of a ticket of type "problem" and where to obtain it. The description only reinforces that the id identifies the problem whose incidents are listed, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource — fetch incident tickets linked to a problem ticket — and grounds it in the Zendesk problem/incident relationship. It is clearly distinguishable from get_ticket (full description) and list_tickets (all tickets) by 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?

Gives a concrete usage context: "useful to gauge a problem's blast radius before resolving it." It also names an alternative (get_ticket) for the full description. No explicit when-not guidance or mention of siblings like search_tickets, but the intended scenario is clear.

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, including where to obtain the id. The description only echoes 'numeric id', so this is the baseline 3 for a schema that does the lifting.

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

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

States a specific verb (Retrieve) and resource (a single organization) with the keying constraint (numeric id), and explicitly contrasts the richer payload against what search or list_organizations return. An agent can distinguish it from list_organizations without opening either schema.

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

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

Explicitly routes the agent: use this for a known numeric id, use list_organizations to browse or do a name-based lookup. That names both the alternative and the condition that selects it.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context beyond them: internal agent notes are never returned on this path, so no agent-private data can leak. It also discloses the security-relevant quirk that a foreign request returns "permission denied" rather than "not found", which changes how an agent should interpret the error.

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 sentences are dense but front-loaded: purpose and return shape first, then the privacy guarantee, then the permission-denied caveat, then sibling routing. Every sentence carries information an agent needs, with no filler or restatement of the name.

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 only two parameters, no output schema, and simple annotations, the description supplies everything needed: what is returned, what the optional parameter adds, what is deliberately excluded, and how errors should be read. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: with include_comments, each message is labelled with its author and flagged when that author is a support agent. It also explains the cost tradeoff implied by the default, though the include_comments wording overlaps substantially with the schema text.

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

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

Opening sentence names a specific verb and resource with an explicit scope: reading one of the signed-in user's own requests, optionally with the full conversation. It also names the sibling it is not (get_ticket) and points to list_requests for id discovery, so the agent can differentiate it from get_ticket and list_requests without opening any schema.

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

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

It gives concrete routing instructions: use list_requests to find the number, and use get_ticket when an agent is reading a ticket it does not own. That is an explicit when-to-use plus a named alternative, leaving nothing to inference.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, yet the description still adds substantive behavior: it discloses the join between form and field definitions, the ordering of returned fields, and the key limitation that conditional fields are reported as rules rather than resolved. That limitation is exactly the kind of caveat an agent cannot get from the schema or annotations.

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

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

Front-loaded with the core action, then return contents, then workflow placement, then the conditional-rule caveat — a logical order with no filler. The opening clause about walking the user through question by question is slightly redundant with the following sentence, but the paragraph stays tight for the amount of useful detail it carries.

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

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

There is no output schema, so the description must describe returns, and it does: field order, customer-facing labels, required flags, exact dropdown values, and rule objects. Combined with the workflow guidance and default-form behavior, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% and the single form_id parameter is already documented, including the 'omit to describe the account default form' behavior. The description repeats that meaning and adds only that the id comes from list_request_forms, which is marginal value over structured data, so baseline 3 applies.

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

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

States a specific verb and resource: read one request form's fields, in portal order, with labels, required flags, dropdown values and conditional rules. It also explains the internal join with field definitions, which clarifies what the tool actually returns rather than leaving it ambiguous against list_request_forms.

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

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

Explicit sequencing is given: 'Use it after list_request_forms and before create_request', plus the fallback that omitting form_id describes the account default form. That is a clear when-to-use, a named prerequisite sibling, and a next-step sibling, leaving nothing to inference.

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

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

Annotations only declare readOnly/idempotent/openWorld; the description adds substantial behavioral context beyond them: SLA resolved via scoped search and may be absent for high-volume requesters or just-updated tickets, follower/CC lists empty when the Zendesk 'CCs and followers' setting is off, and the comment block is truncated at the character limit. It also explains notification semantics (followers vs CCs vs requester).

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

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

Front-loaded with the core purpose and the returned data before the caveats. It is dense and every clause carries operational meaning, though the follower/CC notification explanation and SLA-push detail make it longer than strictly necessary for invocation.

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 two-param tool with no output schema, the description covers return contents, optionality, missing-data cases (SLA absent, empty follower/CC lists), truncation behavior, and sibling routing. An agent has everything needed to call it correctly and interpret edge cases.

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

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

Schema coverage is 100% so both params are already documented, but the description adds value beyond it: it clarifies what include_comments actually appends, its default rationale, and the truncation/pagination caveat. ticket_id sourcing is also reinforced in the schema. Nuance is added on top of a complete schema.

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

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

States a specific verb (retrieve) and resource (Zendesk ticket by ID) and enumerates the returned payload (fields, SLA block, comments, followers/CCs). It explicitly distinguishes itself from get_ticket_history, list_ticket_comments, and list_sla_policies, so an agent can route correctly without opening schemas.

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

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

Gives explicit when-to-use vs when-to-use-alternative guidance: use get_ticket_history for change history, list_ticket_comments for paged/long threads, list_sla_policies for SLA targets. Also names the exact condition (include_comments on a long ticket) where the alternative wins.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial operational detail beyond them: a 10-page-of-100-comments scan cap with a notice in the response, per-image size limits, an embedded-image cap, and a response-size budget that converts remaining files into an 'omitted' count. These are exactly the degradations an agent needs to anticipate.

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

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

Front-loaded with the action and the return shape, and every clause carries real information (caps, fallbacks, truncation signals) rather than padding. The middle sentence is dense and parenthetical-heavy, making the alternative-to-sibling guidance harder to scan than it needs to be.

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

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

There is no output schema, so the description carries the return-format burden and does: images embedded inline, other files as references with name, id, content type, size and URL, plus explicit explanation of partial results. For a 2-parameter read tool, nothing needed for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema only implies: attachment_ids skips the comments fetch entirely, while omitting it triggers the page-capped comment scan and the truncation message. It also tells the agent where ids come from and how to recover files from unscanned comments.

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

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

States a specific verb + resource: 'Download the files attached to a ticket's comments.' It also distinguishes itself from the nearest sibling by noting that list_ticket_comments returns attachment ids rather than content, so an agent can pick correctly without opening either schema.

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

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

Gives concrete use cases ('to see an attached image, or a file's name, size and download URL') and routes metadata-only needs to list_ticket_comments. It also explains the two invocation modes (pass attachment_ids vs. omit). It stops short of explicit exclusions such as 'do not use for full comment text.'

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Gives concrete triggering questions ('what happened on this ticket?', 'why was it reassigned?', 'when did it go to pending?') and names the alternative tool for a related need (comment text). Also explains why to read oldest-first. This is explicit when-to-use plus alternatives.

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

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

Goes beyond the readOnly/idempotent annotations by disclosing the 'not reached yet' sentinel for in-flight durations and that tickets the caller cannot see are reported as such rather than failing the whole call. These are non-obvious response behaviors an agent cannot infer from annotations or the single-parameter schema.

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

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

Three sentences, front-loaded with the core action and scope, then return contents, then routing and caveats. It is dense but slightly over-enumerated ('assignee-station and group-station counts') for a description whose schema and annotations already carry part of the load.

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

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

No output schema exists, so the description must describe returns, and it does thoroughly: reply/resolution/wait/on-hold times in calendar and business minutes, reopen and reply counts, and key timestamps. Combined with the failure-mode and sentinel notes, an agent has everything needed to call and interpret 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% and the single parameter already documents the 1-100 bound, duplicate handling, ordering and provenance. The description's 'up to 100 tickets in one call' merely restates the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read the elapsed-time metrics ... of up to 100 tickets in one call') and enumerates the metric families returned. It explicitly separates itself from get_ticket, search_tickets and list_sla_alerts by framing this as elapsed-time facts versus live breach countdowns, so an agent can pick correctly without opening schemas.

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

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

Names the alternatives and the condition that selects them: 'for the live breach countdown use get_ticket, search_tickets or list_sla_alerts.' It also clarifies applicability even where no SLA policy exists, which is a real selection question for an agent deciding between SLA tools.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds value by listing the returned fields, which matters since there is no output schema, but it does not address failure modes (e.g., not-found behavior) or permission requirements.

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

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

Two compact sentences: purpose first, then routing guidance. No redundant or filler content, and the lookup constraint is front-loaded.

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

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

For a single-parameter getter with full schema coverage, the definition covers purpose, key, return shape, and sibling routing. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter already documents the numeric id plus where to obtain it (search_users, ticket requester/assignee). The description's mention of 'numeric id' merely reinforces the schema, so baseline 3 is appropriate.

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

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

States a specific verb (retrieve) and resource (a single user) with the exact lookup key (numeric id), which distinguishes it from bulk/list siblings. It also enumerates the return payload (name, email, role, organization, tags).

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

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

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

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description still adds real behavior: title matching is case-insensitive, a no-match returns available titles rather than erroring, results are cursor-paginated, descriptions are truncated to a 200-character excerpt, and only the closest SLA metric is included. What it doesn't state is result size/limits or what happens with an unknown numeric id — a small remaining gap.

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

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

Front-loads purpose and sort-order semantics, then layers in matching behavior, pagination, SLA, and truncation — each sentence carries information. It is dense with em-dash parentheticals and slightly longer than needed, but no sentence is filler.

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

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

With no output schema, the description still tells the agent what comes back (same fields as list_tickets, cursor pagination, next-SLA-breach field, 200-char description excerpt). Combined with the fully documented schema and safety annotations, an agent has everything needed to call this correctly on the first try.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantic framing the schema only implies: the view is addressed by title or numeric id with a recoverable no-match path, and sort_by/sort_order are positioned as overrides of the view's configured order rather than the default behavior. That override relationship is the key thing an agent must understand before passing those optional params.

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

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

States a specific verb and resource ('Read the tickets inside a Zendesk view') plus the defining scope: the view's own configured sort order. It cleanly separates itself from siblings by naming list_views for discovery, list_tickets as the field-equivalent, and get_ticket/search_tickets for full data.

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

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

Gives explicit when-to-use framing ('the natural way to work a named queue like "Unassigned tickets"'), names list_views as the prerequisite for discovering the view argument, and routes agents elsewhere for adjacent needs: get_ticket or search_tickets for every SLA metric, get_ticket for the full description.

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

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

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

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

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

Three tight sentences, front-loaded with the core action, then return shape, then sibling routing. Every sentence earns its place with no redundancy.

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

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

For a single-parameter list tool with no output schema, the description covers purpose, return contents, scope boundary, and sibling alternatives. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% (article_id is fully documented), so the schema carries parameter semantics. The description adds no syntax, format, or filtering detail about article_id, so baseline 3 applies.

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

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

States a specific verb and resource ("List all attachments for an article") and immediately scopes it to Help Center articles, distinguishing it from get_ticket_attachments and create_article_attachment. An agent can identify the correct tool without opening the schema.

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

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

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

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

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

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

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

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

Front-loads the core purpose in the first clause, then adds filtering, sorting, and the pagination caveat in tight, waste-free sentences. No redundancy that could mislead.

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

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

For a read-only listing tool with no output schema and full schema coverage, the description supplies everything needed to call it correctly: scope, return granularity, optional filters, sorting, and the pagination re-send caveat.

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

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

Schema coverage is 100%, so the schema already documents all seven parameters in detail. The description adds little, and its enumeration of sort_by values ("title", "created_at", "updated_at") is actually incomplete versus the schema, which also includes "position" as the default.

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

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

States a specific verb+resource ("List articles") and immediately bounds the scope ("metadata only, no body"). It also names the sibling get_article as the tool for full content, so an agent can distinguish the two without opening either schema.

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds real behavioral value by disclosing that only metadata is returned and enumerating which fields, which prevents an agent from expecting body content.

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

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

Two short sentences, zero waste, with the payload constraint front-loaded before the routing advice. Every clause earns its place.

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

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

With no output schema, the description compensates by naming the returned fields, and the single parameter is fully documented in the schema. Nothing needed to call this tool correctly is missing.

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

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

There is one parameter and schema description coverage is 100% — the schema already explains article_id and where to obtain it. The description mentions 'locale' only as an argument to the sibling tool, adding nothing about this tool's own parameter, so baseline 3 applies.

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

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

States a specific verb (list) and resource (translations for an article) and immediately scopes the payload: metadata only, no body, with the exact fields (locale, title, draft, updated_at). An agent can distinguish this from get_article or create_article_translation without opening a schema.

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

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

It names the alternative (get_article with locale) and the condition that selects it (full translated content). The 'metadata only, no body' framing also implicitly states when not to use this tool, though there is no explicit exclusion or prerequisite beyond that.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile needs no repetition. The description adds genuinely new behavioral context: entries contain id/name/locale and results are cursor-paginated, which the annotations do not convey.

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

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

Four short sentences, front-loaded with the purpose and followed by hierarchy, return shape, pagination, and parameters. Slightly dense with routing detail, but no sentence is wasted.

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

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

For a zero-required-param list tool with a fully documented schema and annotation-covered safety profile, nothing material is missing; return fields, pagination, locale behavior, and follow-up tools are all covered without an output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by explaining that locale controls the translation used for category names. It also reinforces the pagination model behind the cursor parameter, adding meaning beyond the field labels.

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

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

States a specific verb and resource (list Help Center categories) and immediately locates it in the Guide hierarchy, distinguishing it from list_sections and list_articles. An agent can tell exactly what this returns and where it sits.

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

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

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

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). Beyond that, the description discloses meaningful behavioral nuance: untranslated categories are omitted from list_categories while unpublished drafts may still appear there, and the draft flag here is authoritative. It doesn't cover pagination or exact return shape, but adds real value.

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

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

Front-loads the verb and resource, then adds only information that routes the agent correctly. It is on the longer side, but nearly every clause carries actionable distinction rather than filler.

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

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

With no output schema, the description correctly describes the returned fields, and single-parameter input is fully covered by the schema. An agent has everything needed to select and invoke the tool correctly.

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

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

Schema description coverage is 100% and the single category_id parameter is already fully documented in the schema (including where to obtain it). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the translations of a Help Center category') and enumerates exactly what is returned per locale (localized name, description presence, published vs draft). It clearly distinguishes itself from siblings like list_categories and set_category_translation.

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

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

Explicitly states when to reach for it ('when a category looks wrong in a locale') and why the obvious alternative fails (list_categories omits untranslated categories and lists drafts). It names the fix tool (set_category_translation) and the bulk alternative (find_translation_gaps).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds non-obvious behavioral context beyond that: results are cursor-paginated and must be enumerated by following the returned cursor, and sorting defaults to name. It does not mention auth requirements or rate limits, but the pagination/ordering disclosure is genuinely additive.

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so all five parameters are already documented, including that name_prefix is a prefix match rather than a fuzzy/substring search and the page_size cap of 30. The description paraphrases these rather than adding format or unit detail, so the baseline of 3 applies; the only extra is the workflow intent behind name_prefix, which is more usage than parameter semantics.

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

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

States a specific verb and resource ('List Guide content tags') and immediately defines the domain object as 'end-user-visible labels that help readers find related articles'. It explicitly separates itself from the sibling list_labels by scoping those as 'internal, non-end-user search labels', so an agent can route correctly without opening either schema.

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

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

Gives explicit when-to-use guidance: pass name_prefix and 'do this before create_content_tag to reuse an existing tag rather than fragment the taxonomy'. It also names the alternative tool and the condition that selects it ('For internal, non-end-user search labels, see list_labels'). Both a positive workflow and an exclusion are provided.

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

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

Annotations already declare read-only, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: labels are internal (invisible to end users) and improve Help Center search ranking, plus where labels are consumed by other tools. It does not discuss pagination or result limits, which keeps it below a 5.

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

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

Four tight sentences: what it returns first, then the non-obvious semantics, then how to use the output, then the disambiguation. Nothing is repeated from annotations and no sentence is filler.

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

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

A no-param, read-only list tool with no output schema, and the description supplies the return shape (id + name), the meaning of the resource, and the routing to the right sibling. Nothing an agent needs to invoke or interpret it is missing.

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

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

Zero-parameter tool, so the baseline is 4. The description goes slightly further by pointing at label_names on create_article/update_article as the downstream consumer of the returned names, giving the values practical meaning.

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

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

Specific verb+resource ('List all article labels') plus the return shape (each label's id and name), and it explicitly distinguishes itself from the similarly named list_content_tags. An agent can separate it from siblings without opening a schema.

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

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

States the action to take after listing (attach via label_names on create_article/update_article), advises reusing existing labels over coining near-duplicates, and names the alternative tool with the condition that selects it ('for end-user-visible tags readers browse by, use list_content_tags').

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

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

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

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

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

The purpose is front-loaded in the first sentence, followed by definition, return shape, scoping and routing. It is denser than strictly needed (the macro definition sentence is long), but each clause carries information and nothing is redundant.

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

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

With no output schema, the description compensates by enumerating the returned fields, and it also covers pagination behavior, auth scoping, and the follow-up tool. An agent has everything needed to call and then chain this tool correctly.

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

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

Schema description coverage is 100% and both parameters (page, per_page) are fully documented in the schema itself. The description only notes 'offset-paginated' generically without adding format or default details beyond what the schema already provides, so the baseline 3 applies.

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

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

The description gives a specific verb (List) and resource (active macros), then defines what a macro is and what is returned (id, title, description, availability scope, ordered actions). It clearly distinguishes this from siblings like list_labels and list_views by describing the resource and its scope.

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

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

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

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds value by disclosing the return shape (name/id plus basic fields) and that results are cursor-paginated, though it doesn't mention rate limits or page-size behavior beyond the schema.

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

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

Three sentences, front-loaded with the core action and pagination, followed by alternatives and a brief domain note. Dense and mostly waste-free, though the closing sentence about organizations grouping end users is useful context rather than strictly essential.

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

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

With no output schema, the description appropriately fills the gap by naming returned fields and pagination semantics. It is nearly complete for a simple list tool; only finer pagination termination details are absent, which the cursor parameter largely covers.

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

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

Schema description coverage is 100% and both parameters (cursor, page_size) are fully documented in the schema. The description only restates 'with pagination' and adds no syntax or format detail beyond the structured fields, so baseline 3 applies.

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

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

States a specific verb and resource ('List all organizations with pagination') and immediately names the returned fields, then explicitly distinguishes itself from get_organization and search. An agent can select this over its siblings without opening a schema.

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

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

Gives explicit alternatives and the condition selecting each: use get_organization with an id for full details (tags, domains, notes), or search for query-based lookups by name. This is a clear when-to-use-this vs when-to-use-something-else routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the description correctly focuses on what annotations cannot express: a hard authorization prerequisite that makes the call fail without the Guide admin or Help Center manager role. It doesn't say anything about ordering, size limits, or whether the list is paginated, which is the remaining gap for an open-world list call.

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

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

Front-loaded with purpose and return fields, then usage routing, then the auth caveat — a good information order. The single long sentence with chained semicolons is dense and would scan better split into two or three sentences, but no clause is filler.

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

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

With no parameters and no output schema, the description carries the full explanatory burden and does so: it names the returned fields, the permission prerequisite, the downstream consumers (create_article/update_article), and the sibling that handles the complementary permission concern. Nothing an agent needs to call this correctly is absent.

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

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

The tool takes zero parameters (additionalProperties: false, empty properties), so there is no parameter semantics to convey. Baseline for a parameterless tool applies; no useful parameter information is missing.

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

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

States a specific verb and resource (list Guide permission groups) plus the semantic meaning ('control who can edit and publish an article') and the exact fields returned (id, name, built-in flag). It explicitly distinguishes itself from the sibling that handles the adjacent concern ('to control who can view an article instead, use list_user_segments').

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

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

Gives concrete when-to-use cases: obtaining permission_group_id for create_article or changing it via update_article. It also names the alternative tool (list_user_segments) for the view-permission case and offers a shortcut (reuse the permission_group_id from get_article), covering both branches an agent would face.

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

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

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

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

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

Front-loaded with the purpose and the get_article/update_article routing, then the cost model. It is dense and slightly long, but nearly every clause carries operational value; only minor tightening is possible.

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

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

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

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

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

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

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

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

States a specific verb and resource ('List the promoted ("featured") Help Center articles') and narrows the scope precisely ('the small, editorially-curated set surfaced at the top of their sections'). It explicitly differentiates from siblings: 'use get_article for full content' and 'use update_article with `promoted`' to mutate.

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

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

Gives explicit when-to-use (reading the curated featured set), when-not-to-use (full content belongs to get_article), the mutation alternative (update_article, with the admin-rights prerequisite), and a strong operational caveat to avoid repeated calls. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real context beyond them: only active end-user-visible forms are returned, and a single-form account yields just one result. It also pre-announces the returned fields (name, id, default flag), which the absent output schema would otherwise leave unknown. The only gap is that it does not discuss pagination or result-size behavior if the hint of multi-form accounts scales.

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 the identity of the resource, then the sequencing rule, then the scoping caveat, then the sibling exclusion. No redundant restatement of the title and no wasted clauses.

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

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

For a zero-parameter read tool with no output schema, the description covers purpose, sequencing, filtering semantics, and return shape, which is enough to call it correctly. Only result-volume or pagination behavior is unstated, a minor omission for a typically small list.

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

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

There are zero parameters and 100% schema coverage, so the schema carries the full burden and the description correctly stays silent on inputs. Baseline applies; nothing further 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?

States a specific verb and resource ("List the kinds of request you can submit") and immediately concretizes it with the Help Center form examples "Report a bug" / "Feature request". It also names the two siblings it is not (list_ticket_fields, create_ticket), so an agent can route without opening another schema.

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

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

Gives an explicit ordering rule ("Call this first when opening a request ... then get_request_form") and an explicit exclusion with the alternative for the agent/assist use case. Both when-to-use and when-not-to-use are covered.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses the crucial scoping rule that Zendesk enforces caller-scoping so the tool can never return another user's tickets, plus the default ordering and the fields returned per request (number, subject, status, solvability). The openWorldHint annotation is not contradicted — the scoping claim is about the API's authorization boundary, not reach.

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 what the tool returns before moving to alternatives. Dense but nearly every clause carries information; the scoping explanation is slightly long-winded relative to the rest.

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

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

No output schema exists, yet the description enumerates the returned fields and flags the per-item solvability check, and the pagination/total-count behaviour is documented in the parameter descriptions. For a six-parameter read-only list tool whose annotations already cover safety, nothing an agent needs 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 earns an extra point by explaining that supplying `query` switches the tool to the search endpoint rather than filtering a listing, and by noting results are newest-activity-first by default. It stops short of covering pagination behaviour, which the schema already handles.

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

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

The description states a specific verb and resource ("List the requests the signed-in user submitted") and immediately contrasts it with get_request for single-request reads and with list_tickets / search_tickets / get_view_tickets for queue-style work. An agent can distinguish this from every relevant sibling without opening a schema.

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

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

It gives explicit when-to-use guidance (own submissions, not a queue), a documented alternative path within the same tool ("pass a query to search their own requests ... instead of listing all of them"), and names the correct sibling tools for the queue case. Both the positive case and the exclusion are stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low. The description adds real behavioral context the annotations lack: results are cursor-paginated and locale defaults to the Help Center default if omitted. It stops short of describing ordering or empty-page behavior.

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

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

Front-loaded with purpose, then hierarchy, return fields, pagination and workflow in four tight sentences. Each sentence carries distinct information, though the hierarchy explanation is somewhat parenthetical to the call itself.

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

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

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

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

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

Schema coverage is 100%, so the schema already documents cursor, locale, page_size and category_id with types, defaults and bounds. The description largely restates these ('ids come from list_categories', 'pass a locale'), adding only light sourcing context rather than new semantics. Baseline 3 applies.

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

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

States a specific verb+resource ('List Help Center sections') and situates it precisely in the Guide hierarchy (category → section → article), which cleanly separates it from siblings list_categories and list_articles. It also enumerates the returned fields, so an agent knows exactly what it gets.

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

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

Explicitly routes the agent: pass category_id (which comes from list_categories) to scope to one category, then use a returned section id with list_articles. This names the prerequisite call and the downstream call, covering both when and how to use it.

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

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

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

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

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

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

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

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

With no output schema, the description compensates by describing the returned fields, and it supplies the parameter's origin, the disambiguating rules, and both follow-up routes. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% and the single section_id parameter is already documented in the schema, including its source (list_sections or the topology resource). The description adds no further syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the translations of a Help Center section') and enumerates the returned fields (localized name, description set, published/draft). It explicitly distinguishes itself from the sibling list_sections by naming the exact situation where the two differ.

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

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

Gives an explicit trigger ('when a section looks wrong in a locale'), explains why the obvious alternative (list_sections) cannot answer the question, and names both the remediation tool (set_section_translation) and the bulk alternative (find_translation_gaps). Nothing about when-to-use vs alternatives is left to inference.

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

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

Goes well past the readOnly/idempotent annotations: results are cached per user for about a minute, sets larger than a few hundred tickets are partially read with a notice, paused and achieved metrics never appear, and thresholds are resolved per metric family. It even discloses the one side effect (remembering in per-user state that thresholds were shown) rather than hiding it behind readOnlyHint.

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

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

Dense but front-loaded, leading with purpose and the scope/view/query choice before the output-format and threshold detail. The single long semicolon-chained sentence carrying the display-format rules is harder to scan than it needs to be, but little of the content is filler for a seven-parameter 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?

For a read-only list tool with no output schema, the agent gets output shape (one line per metric under BREACHED/CRITICAL/WARNING with id, metric, time left, subject, status, priority), caching and truncation behavior, threshold resolution order, and where to go for adjacent needs. Nothing material is missing.

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

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

Schema coverage is already 100%, but the description adds real meaning: the mutual exclusivity of scope/view/query, how a lone warning lowers critical and a lone critical raises warning, and that each running metric is only listed if closer to breach than its threshold. The within/include_breached interaction is described but only by pointing back at the schema.

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

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

States a specific verb and resource ("List the SLA metrics that are breached or about to breach across a set of tickets, most urgent first") including the ordering and the inclusion rule. It also explicitly distinguishes itself from get_ticket and get_ticket_metrics, which are the closest siblings.

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

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

Gives an explicit selection rule — "exactly one of scope (...) view (...) or query" — and names the follow-up tools for the adjacent jobs (get_ticket for a single ticket's SLA state, get_ticket_metrics for elapsed times). It also documents the no-argument fallback: the client may be prompted, otherwise it defaults to the caller's own tickets and says so.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly focuses on what annotations cannot convey: the admin-token requirement and the concrete 403 failure mode for standard agent tokens, plus the workaround. It stops short of describing pagination behavior or output shape details beyond the field list, but the auth disclosure is genuinely additive.

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

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

Front-loaded with the resource and payload, then usage, then access constraints. Two sentences with no filler, though the second sentence is dense and could be split for readability.

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

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

With no output schema, the description carries the return-value burden and does so at a summary level (filters + per-priority targets) while covering auth and pagination. Adequate for a read-only list tool, short only of exact field-level detail.

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

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

Schema description coverage is 100% and both page/per_page descriptions already explain offset pagination, total-count headers and the 100 cap. The description adds nothing about the parameters, so the baseline 3 applies.

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

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

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

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

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

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

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

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

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

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

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

Front-loaded with purpose and returns, followed by tool routing and parameter guidance — a sensible ordering. It is dense and the final sentence runs long, but each clause carries a distinct routing or behavioral fact rather than filler.

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

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

With no output schema, the description enumerates the returned fields (comment id, resolved author name, timestamp, public/internal flag, attachment ids), and it covers pagination, ordering, and sibling alternatives. An agent has everything needed to invoke and use the result correctly.

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

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

Schema coverage is 100%, so much of the parameter detail duplicates the schema (cursor semantics, page_size bounds, sort_order enum). The description still adds decision-level guidance — keep the default 'desc' for the latest reply, follow the cursor rather than raising page_size — which is meaning beyond the raw field definitions.

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

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

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

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

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

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

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

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

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

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

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

Front-loaded with what it returns, then why to call it, then behavioral notes. Three dense sentences with no filler; every clause earns its place.

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

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

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

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

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

Schema description coverage is 100%, so cursor and page_size are fully documented in the schema itself. The description only alludes to pagination generally and adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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

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

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

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

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

Explicitly states when to use it: to discover numeric field ids and option tags that create_ticket and update_ticket expect in custom_fields, with a concrete example ('set severity to High'). This routes the agent to the correct tool and names the downstream alternatives.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so safety is covered. Beyond that the description discloses two non-obvious traits: the non-recency default ordering and that each ticket's description is truncated to a 200-char excerpt (with get_ticket as the escape hatch). It does not describe the response envelope or page-limit exhaustion behavior, but the truncation and ordering caveats are exactly the kind of context annotations cannot carry.

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

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

Four tight sentences, each carrying a distinct fact: ordering, page-size naming trap, pagination mechanics, and the search_tickets alternative plus truncation note. Front-loaded with the ordering caveat, which is the highest-risk assumption an agent would make.

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

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

For a two-parameter read tool with no output schema, the description covers pagination, ordering, and the data-fidelity caveat an agent needs to decide whether to follow up with get_ticket. Minor gap: it doesn't characterize the returned list shape or whether an empty cursor signals the last page, both of which matter for loop termination.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot: it warns that page size is page_size, not per_page (the offset-based parameter on search_tickets), heading off a likely misuse, and clarifies that cursor values come from prior responses. That is genuine added semantics rather than restatement.

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

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

States a specific verb and resource ('List tickets') and immediately pins down scope and ordering: cursor-based pagination, Zendesk default ascending ticket id order, not recency. It explicitly contrasts with search_tickets, so an agent can distinguish the two without inspecting either schema.

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

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

Explicit routing: use this tool for straight ticket enumeration; use search_tickets with a query for recency or any other criterion. It also tells the agent to paginate by passing the returned cursor, covering the continuation path.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description does add material context the annotations lack — Zendesk restricts the call to Guide admins and Help Center managers and it fails without that role — but it says nothing about ordering, pagination, or limits. That added auth/failure detail is real value, though not rich enough to warrant a top score.

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?

Information is front-loaded: what segments are, then the returned fields, then the id handoff, then the auth caveat. It is dense and largely earns its space, but it runs long with the trailing create_article default-behavior clause appended in the same breath, making it a heavy single block.

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

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

For a zero-parameter read tool with no output schema, the description covers purpose, return fields, auth requirement, and downstream id usage. An agent has everything needed to decide to call it and to interpret the result.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The only semantics mentioned (user_segment_id) belong to other tools, not this one's inputs.

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?

Names a specific verb and resource ('List all Help Center user segments'), then explains what a segment actually is — it controls article visibility — and enumerates returned fields (id, name, user type, built-in). This is clearly distinguishable from list_permission_groups, which it explicitly names as the sibling for a different concern.

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

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

Gives explicit routing: use this tool's id as user_segment_id in create_article/update_article, use list_permission_groups instead to control edit permissions, and reuse the segment id from get_article or omit it to default to everyone-visible. Both the when-to-use and the alternatives are spelled out.

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

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

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

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

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

Front-loads the core purpose and keeps to one dense paragraph where each clause (examples, counts, scoping, staleness, hand-off) carries information. Slightly long and clause-heavy, but no filler sentences.

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

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

With no output schema, the description still conveys the return shape (views each with a ticket count) and the caveat about stale counts. Combined with the annotated safety profile and a fully covered 2-param schema, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so cursor and page_size are already fully documented in the schema. The description adds no parameter-level detail (no mention of pagination or page-size tradeoffs), so the baseline 3 applies.

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

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

States a specific verb and resource (list Zendesk views) and immediately grounds it with concrete examples ('Unassigned tickets', 'My open tickets') and the payload (views with current ticket counts). It also names the sibling get_view_tickets as the follow-up tool, so an agent can distinguish it without opening either schema.

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

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

Clearly signals the context of use ('tell at a glance where the workload sits') and hands off explicitly to get_view_tickets for drilling into tickets. It lacks an explicit when-not-to-use statement or a mention of list_tickets/search_tickets as alternatives, so it stops short of the top band.

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

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

Annotations declare idempotent/destructive/openWorld, but the description adds the mechanism the annotations cannot express: an incremental read-modify-write that merges rather than replaces, collapses duplicates, leaves unlisted tags untouched, and returns the full post-update tag set. This is exactly the kind of beyond-annotation context that prevents data loss.

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

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

Front-loaded with the core action, then mechanics, then routing to alternatives. Dense and mostly waste-free, though the mechanics and idempotency points could be trimmed by a sentence without losing meaning.

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

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

Though there is no output schema, the description states the return value ('full tag set after the update'), the mutation semantics, and the sibling routing. Nothing an agent needs to call this correctly and safely is missing.

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

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

Schema coverage is 100% and already documents add/remove omission and no-op semantics, so the baseline is 3. The description goes slightly beyond the schema by stating the merge/duplicate-collapse behavior and that unlisted tags survive, which clarifies how the two arrays interact.

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

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

States a specific verb pair and resource ('Add or remove tags on a ticket') and immediately names the sibling it is not for ('to overwrite the entire tag set at once ... use update_ticket instead'). An agent can distinguish it from update_ticket or create_content_tag without opening any schema.

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

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

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

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

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

Annotations already flag mutation, destructiveness, idempotency and open-world reach, but the description adds genuinely new behavior: it returns the status read back from Zendesk rather than an acknowledgement, and it self-refuses unless the request is solvable because Zendesk returns 200 while changing nothing. The no-op-on-already-solved note reinforces but largely restates idempotentHint=true, which keeps this just short of a 5.

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

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

Front-loaded with the action, then failure modes, then alternatives; no sentence is filler. It is a single dense block with long subordinate clauses ('because Zendesk answers 200 and changes nothing when it is not, which would otherwise be reported as success'), which costs some scannability but not accuracy.

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

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

There is no output schema, and the description compensates by describing the return value (status read back from Zendesk) and the misleading-success trap. Combined with the prerequisite, no-op behavior and fallback path, nothing needed to call this correctly or interpret its result is missing.

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

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

Schema coverage is 100% and the single parameter is already documented, so the baseline is 3. The description adds constraint meaning the schema lacks: the request must belong to the signed-in user and must be solvable (agent assigned), which tells the agent which request_id values are even valid.

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

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

States a specific verb and resource with explicit scope: 'Close one of the signed-in user's own requests, for when they consider it resolved.' It also distinguishes itself from the sibling that handles the agent-side equivalent ('Agents closing a ticket want update_ticket with status solved'), so the agent can route without opening either schema.

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

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

Gives explicit when-to-use (requester considers it resolved), when-not (brand-new or unassigned requests cannot be closed this way) plus the fallback action (reply with add_request_comment), and names the sibling for the agent-side case (update_ticket). Every branch an agent could land in is covered.

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

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

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

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

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

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

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

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

With no output schema, the description carries the burden of describing the return value, and it does so precisely (only changed fields, reply with its visibility flag, omissions noted). No annotation or schema gaps remain for an agent to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so both integer parameters are already documented in the schema, including where to obtain them. The description repeats that sourcing guidance but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

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

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

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

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

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

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

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

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

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

Front-loaded with the action and scope, then layered caveats, with zero filler sentences. It is dense and slightly long, but nearly every clause carries decision-relevant information.

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

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

Covers the action, the exclusion, the failure mode (auto-sorted sections), the safety gate, and even the return value ("return whether the new order was applied") in the absence of an output schema. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter including target, confirm, and normalize is already documented in the schema. The description restates the confirm/threshold behavior but adds nothing beyond the schema and never mentions normalize. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource (reorder an article within its current section) plus the precise mechanism (relative to siblings: top, bottom, before/after). It explicitly contrasts itself with the sibling update_article for cross-section moves, so an agent can distinguish it without opening a schema.

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

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

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

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low; the description goes well beyond by disclosing result truncation (200-character ticket description excerpt) and that organization results return name and ID only. That is exactly the kind of output-shape behavior an agent cannot infer from structured fields.

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

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

Three sentences, no filler, and the most important scoping information (what is searched, pagination limits, truncation) is front-loaded. Every clause carries actionable 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?

There is no output schema, yet the description explains the return shape: total count, pagination size bounds, excerpt truncation, and reduced organization fields. Combined with 100% schema coverage, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the schema already documents page, query, and per_page in detail. The description restates the filter syntax and pagination defaults but adds no new parameter semantics beyond what the schema provides; 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?

Opens with a specific verb and enumerates exactly which resource types are covered (tickets, users, organizations), which is enough to separate it from the ticket-only sibling search_tickets. The scope is unambiguous without opening any schema.

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

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

Gives concrete filter syntax examples and explicit downstream routing: 'use get_organization for full details' and get_ticket for the full description. It does not explicitly say when to prefer search over search_tickets or list_tickets, so the sibling selection guidance is implied rather than stated.

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

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

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

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

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

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

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

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

With no output schema, the description usefully states that a total count is returned, and annotations carry the safety profile. Pagination and query semantics live in the schema. What is missing is only marginal – ranking/relevance behavior and how results are ordered.

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

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

Schema description coverage is 100% – each of the four parameters is documented in the schema, including pagination mechanics. The description only echoes locale filtering, which the schema already explains, so a baseline 3 is appropriate.

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

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

States a specific verb and resource ('Full-text search across Help Center articles') with an explicit scope qualifier ('metadata only, no body'). It also names the sibling tool that serves the complementary need (get_article), so an agent can distinguish it without opening either schema.

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

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

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

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds substantial behavioral context beyond them: SLA blocks appear only when a policy applies, an Urgency line appears only when the operator enabled SLA push, and ticket descriptions are truncated to 200 characters. Those conditional and lossy behaviors are exactly what an agent could otherwise misread.

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

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

Front-loaded with the core action and output shape, and every sentence carries information (examples, count for triage, Urgency line, truncation). Slightly dense — the Urgency-line sentence is niche and could be tightened — but nothing is redundant.

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

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

With no output schema, the description carries the return-value burden and does so: total count, per-metric SLA stage and breach countdown, optional Urgency classification, and the 200-character description excerpt with a pointer to get_ticket. Pagination is handled by the schema, so nothing an agent needs is missing.

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

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

Schema description coverage is 100% and the schema already documents query syntax, the auto-added type:ticket scope, group:me handling, and pagination pairing. The description's example queries largely restate what the schema shows, adding no new parameter 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?

States a specific verb and resource (search tickets) plus the query dialect (Zendesk query syntax) and the distinctive enrichment it returns (live SLA state per metric). This clearly separates it from list_tickets (unfiltered listing) and get_ticket (single full record), which the description names explicitly.

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

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

Concrete example queries and the 'queue triage like breaching today' scenario tell the agent exactly when this tool shines, and the closing note routes full-description needs to get_ticket. It stops short of explicit exclusions (e.g. when to prefer list_tickets or list_views instead), so not quite a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description still adds real behavioral context: the result set is multi-valued and a name can match several users, so the agent must confirm identity, and it discloses the returned fields. It stops short of discussing pagination limits, though the schema covers those.

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

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

Three sentences, front-loaded with the verb, resource and return shape, then routing guidance. Dense but each clause carries routing or behavioral value; the sibling enumeration is long but justified given how many near-neighbors exist.

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

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

There is no output schema, yet the description enumerates the returned fields and the total count, warns about ambiguous name matches, and routes to the right sibling in every case. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, so `query`, `page` and `per_page` are fully documented in structured data. The description's mention of "name, email, or other criteria using Zendesk search query syntax" largely restates the schema's query description rather than adding new semantics. Baseline 3 applies when the schema carries the weight.

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?

Names a specific verb and resource (search for users) and spells out exactly what each match returns: id, name, email, role, active flag, organization id, plus total count. It also positions itself against three named siblings (get_user, get_current_user, search), so an agent can pick it without opening a schema.

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

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

Gives explicit when-to-use (turn a person into a numeric user id for tools like update_ticket), two explicit alternatives with conditions (get_user when you already have an id, get_current_user for your own account), and an explicit preference rule over `search` when only users are wanted.

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