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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing what is returned: markdown-ish text, headings, badges such as Deprecated, and lifecycle classification.

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

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

One tightly written sentence that front-loads the core action and follows with the return shape. Nothing is padded, though the two halves (what it fetches, what it returns) could be split more cleanly for 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 carries the burden of describing results and does so adequately (markdown text, headings, badges, lifecycle classification). For a single-parameter, read-only fetch tool this is sufficient; only cross-page navigation guidance 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 a single parameter with 100% schema description coverage, and the schema already states the url must be on developer.zendesk.com. The description adds no extra format, canonicalization, or redirect-handling 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?

States a specific verb (fetch and clean) and a specific resource (one developer.zendesk.com page), and enumerates the page kinds it handles (API reference, guide, changelog). The word 'one' implicitly separates it from sibling search_developer_docs, but it never names that sibling 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?

Usage is only implied by 'one ... page' and the URL constraint. There is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives such as search_developer_docs or get_feature_lifecycle, which an agent could easily confuse with this tool.

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

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

Annotations already establish that this is a safe, idempotent, read-only, open-world call, so the bar is lower. The description still adds real value by disclosing the internal behavior: it searches three source classes (Help Center, developer docs, change feeds) and can surface conflicting sources alongside a preferred one, which tells the agent how much to trust the result.

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, front-loaded with the composite nature and usage examples before the mechanics of sources and return shape. Nothing is wasted, though the run-on second sentence 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 correctly carries the burden of describing returns, enumerating the verdict vocabulary (current/future/beta/eap/deprecated/legacy/retired) and the preferred/conflicting source field. The only meaningful gap is the unexplained locale parameter and no note on latency or source-freshness limits.

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

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

The schema documents 'feature' but leaves 'locale' with only a regex pattern and no explanation, and the description says nothing about either parameter. With coverage around 50%, the description was expected to compensate for the undocumented locale (e.g., that it controls document language) but does not.

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 action (composite lookup) and a specific resource (a Zendesk feature's lifecycle status), with concrete example questions. It is clearly distinguishable from siblings like search_help_center or get_developer_page because it aggregates them into a single verdict rather than returning raw documents.

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

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

The example questions ('Is offset pagination deprecated?', 'Is Copilot GA?') give a strong signal of when this tool is the right entry point instead of the underlying search tools. However, it never explicitly states when NOT to use it (e.g., for reading a specific doc, use get_help_article), so routing guidance is implied rather than 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?

Annotations already declare readOnly, idempotent, open-world and non-destructive, lowering the bar, and the description still adds return-shape context: cleaned full text, truncation for very long articles, plan banners, breadcrumbs, dates and lifecycle classification. No auth, rate-limit or locale-fallback behavior is disclosed, 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?

Two sentences, no filler, with the input contract front-loaded and the return contents following. Every clause carries 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 simple read tool with no output schema, the description covers input forms and the salient parts of the return payload, while annotations cover the safety profile. Missing only explicit error behavior for bad ids or unknown locales.

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

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

Schema coverage is 100% and both parameters are documented there, including the locale default and the id/URL example, so the baseline of 3 applies. The description restates the id/URL duality but adds no syntax or format detail beyond the schema.

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

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

States a specific verb+resource ('Fetch one official Help Center article') and the accepted identifiers (numeric id or support.zendesk.com URL). The 'one article by id' framing implicitly and cleanly separates it from the sibling search_help_center, so an 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?

Usage is implied by the required identifier: use this when you already have an article id or URL. However, it never states when to prefer it over search_help_center or what to do when the id is unknown, so the guidance is only inferable.

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 new context: that results are aggregated from two distinct domains and that each item carries a change_type taxonomy (breaking_change, deprecated, beta, eap, etc.), dates and lifecycle. It does not discuss rate limits or freshness, 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?

Two dense but efficient sentences, with the core value proposition ('What changed and when') front-loaded. The parenthetical source lists are long but earn their place by mapping to the feeds enum.

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, but the description compensates by describing the shape of returned items (change_type values, dates, lifecycle). Combined with annotations covering the safety profile and an 80%-covered input schema, an agent has enough to call this correctly, though source/ordering semantics (how merged results are sorted) remain unstated.

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 80%, so the schema already documents feeds, limit, query, since and locale. The description reinforces the feed concept by naming Announcements, Developer updates, Release notes and What's new, but adds no syntax or filtering 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?

The description states a specific resource (Zendesk changes) and precisely identifies the merged sources: developer.zendesk.com changelog plus the support.zendesk.com 'Zendesk updates' feeds. It is distinguishable from search_developer_docs and search_help_center, though it does not explicitly contrast with get_feature_lifecycle despite mentioning lifecycle 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?

No when-to-use guidance is given. The description never states when an agent should pick this over get_feature_lifecycle or search_developer_docs, and there are no exclusions or prerequisites. Usage must be inferred from the topic coverage alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds real value beyond that: the data source, that only live/maintenance data exists, and that resolved incidents cannot be retrieved. It does not mention auth requirements or rate limits, which keeps it from 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?

Two tight sentences, front-loaded with what the tool returns before the data-source detail and the limitation. No filler, no repetition of the title.

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

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

For a single-optional-parameter read tool with rich annotations and no output schema, the description supplies everything an agent needs: the resource, the source, the optional filter, and the key coverage limitation. No return-format explanation is required in the absence of 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?

There is one optional parameter and schema description coverage is 100%, with the schema itself explaining the subdomain format, so the baseline is 3. The description adds only that filtering is optional ('optionally filtered to a subdomain'), a marginal gain over 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 resource (live active incidents and upcoming maintenance) and names its authoritative source (the official Zendesk Status API at status.zendesk.com), which naturally separates it from siblings like get_zendesk_changes or get_help_article. An agent can predict the returned content 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?

Gives clear context (checking system health/incidents, optionally scoped to one subdomain) and states an explicit limitation — historical/resolved incidents are unavailable — which effectively tells the agent when this tool will fail to answer. It stops short of naming an alternative tool for historical or changelog data.

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/non-destructive, so the safety profile is covered. The description adds meaningful process detail beyond that: URL-slug ranking from a sitemap, live fetching of top pages, and deprecation badge surfacing – genuinely useful behavioral context.

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: what it searches, how it ranks/fetches, and how to phrase the query. Front-loaded with purpose and zero filler.

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

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

No output schema exists, yet the description discloses what results contain (title, snippet, deprecation badges), and it explains the fetch_pages tradeoff. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 75% and documents section, fetch_pages, and max_results. The description complements this by explaining the URL-slug query phrasing (the one undocumented param), which adds real meaning beyond the bare string type.

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 (search) and resource (developer.zendesk.com), and narrows scope to API reference, apps framework, and SDKs. This cleanly distinguishes it from sibling search_help_center without needing to name it.

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

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

Gives concrete query-construction guidance ('use endpoint/resource names as they appear in URLs') with examples ('ticket audits', 'webhooks'). It lacks explicit when-not-to-use/exclusion guidance versus siblings like get_developer_page, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds genuinely useful context beyond that: the exact result fields returned (title, snippet, canonical URL, updated date, product, plan requirements, lifecycle status) and the fact that results are paginated and exclude community posts. It is somewhat under-specified on pagination limits, which the schema carries instead.

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, front-loaded with the scope constraint and then the return payload, with zero 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?

With no output schema, the description compensates by enumerating the returned fields and noting pagination and the exclusion of community posts, and the fully-covered input schema handles parameters. Only minor gaps remain, such as pagination bounds and result ordering, which are not strictly required to call the tool correctly.

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

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

Schema description coverage is 100%, so all five parameters (query, page, per_page, locale, product) are already documented, including defaults and the 'soft filter/boost' nature of product. The description adds nothing parameter-level except a nod to pagination, 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 (search) plus resource (Zendesk product documentation on support.zendesk.com) and explicitly scopes the corpus: 'articles only; community posts are excluded'. It also implicitly separates itself from get_help_article (single article) and search_developer_docs (developer docs), though it never names a sibling, which keeps it short of a 5.

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

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

Usage is implied by the scope statement — reach for this to find Help Center articles by keyword — but there is no explicit when-to-use guidance or routing directive to alternatives such as get_help_article for a known article or search_developer_docs for developer content. Adequate but leaves selection to inference.

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