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

Annotations already declare non-readOnly, non-idempotent, non-destructive, open-world; the description adds genuinely new behavioral facts beyond them: the default unpublished/draft state and how body text is interpreted (blank lines become paragraphs). It doesn't cover side effects like slug auto-generation or whether categories must pre-exist.

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

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

Three short sentences, front-loaded with the verb and resource, then the most consequential default (draft) and the content-format caveat. Nothing is wasted.

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

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

Adequate for a 7-parameter mutation with annotations and full schema coverage, but it is silent on codename behavior (auto-generated?), language defaults, and what the call returns (an article id is needed for follow-up update_article/get_article, and no output schema exists).

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 including body format and the published default. The description's only additive semantic is the blank-line-to-paragraph conversion, 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+resource ("Create a new article") and immediately adds the key state outcome (unpublished draft unless published=true). It is clearly distinct from update_article/delete_article by name, though it never explicitly contrasts with them or with create_category.

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 published=true clause gives real conditional guidance on the draft-vs-live decision, but there is no explicit when-to-use-this-vs-alternative advice (e.g. use update_article to modify an existing one, or when to set codename manually).

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=false, destructive=false, openWorld=true and idempotent=false, so the safety profile is covered. The description adds nothing beyond that: it does not mention permission requirements, duplicate-name behavior, or the fact that repeated calls create multiple categories (non-idempotent).

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

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

One short sentence with the resource front-loaded and no filler. It is efficient, though the brevity comes at the cost of detail rather than being a structural flaw.

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 four parameters, no output schema and only 50% schema coverage, the description leaves out the accessibility option, permission/auth expectations, and any sense of what is returned on success. An agent could invoke it correctly for a simple case but would be blind to the visibility setting.

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

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

Schema coverage is 50%, with parentId and accessibility documented in the schema but name and description not. The description only echoes the nesting behavior already stated in the parentId schema field and says nothing about the accessibility parameter, which has real visibility consequences (public = everyone).

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 ('Create a knowledge base category') and notes the nesting option, which distinguishes it from the read-oriented siblings like list_categories and get_category. It stops short of explicitly naming an alternative, but no other sibling creates categories, so the agent can select it correctly.

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 the verb 'Create' and the phrase 'optionally nested under a parent'. There is no guidance on prerequisites (e.g. having an existing parentId, locating one via list_categories) or on when not to use this tool.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is known. The description adds genuinely useful behavioral context beyond that: the human-confirmation requirement and the softer alternative. It stops short of saying whether deletion is permanent or what happens to linked 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 compact sentences with the action stated first and the caution immediately after; nothing is wasted.

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

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

For a one-parameter destructive tool with full annotation coverage and no output schema, the definition supplies what the agent needs: the target, the confirmation step, and a safer alternative. Minor gap in not describing irreversibility or downstream effects.

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 articleId parameter is already documented with its source. The description adds no parameter-level information, 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 ('Delete an article from the knowledge base'), which clearly separates it from siblings like update_article or get_article. It does not explicitly name the sibling to use for the safer alternative, keeping it below 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?

'Confirm with the user first; consider unpublishing instead' gives a concrete precondition and an alternative course of action. The alternative is not tied to a named tool, so the agent must infer which sibling performs unpublishing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine scope detail — only 'published' articles, results ordered oldest first, default 180-day threshold — but says nothing about truncation when the scan limit is hit or what a result record contains.

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 filter and ordering come first, then the use case. Every clause carries information an agent needs.

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, fully-optional read-only tool this is nearly sufficient; annotations and schema cover safety and inputs. The only real gap is that no output schema exists and the description doesn't hint at the returned fields or whether results are capped by the scan limit.

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 (days, limit, categoryId) are already documented with defaults and bounds. The description only restates the default day threshold and adds the sort order; it adds nothing about how limit interacts with scanning or how categoryId scoping affects results.

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

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

States a specific verb and resource plus the defining predicate (published, not updated in N days) and the result ordering (oldest first). This clearly separates it from generic siblings like list_articles or search_knowledge_base, though it never names those siblings 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?

The clause 'Useful for content audits before a release' implies a usage context but gives no explicit when-to-use vs. when-not, no mention of list_articles or search_knowledge_base as alternatives, and no prerequisites. Usage must be inferred from the filter semantics.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the returned field list, which is genuinely useful given there is no output schema, but says nothing about auth requirements, caching, or what openWorld network access implies.

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 sentence, front-loaded with the verb and resource, and the parenthetical field list earns its place by substituting for a missing output schema. No filler.

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

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

For a zero-parameter read with annotations covering the safety profile, listing the returned fields fills the main gap left by the absent output schema. Only minor behavioral context (auth, whether settings are workspace- or tenant-scoped) is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies no input is needed, and the listed fields read as outputs rather than confusing them with 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?

States a specific verb ('Get') and a specific resource ('knowledge base account settings') and enumerates the returned fields (name, subdomain, internal KB flag, contact email). This clearly separates it from the article and category siblings, none of which touch account-level configuration.

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 — an agent can infer it should call this when it needs account-level metadata, but the description never says when to prefer it over, say, search_knowledge_base, nor does it state any prerequisites. No exclusions or alternative routing 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 already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuine behavioral value by describing the default output ('clean plain text, internal blocks expanded') and the alternative HTML mode, which matters since there is no output schema. It says nothing about missing-article behavior or error cases.

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 what the tool does, then what it returns. 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?

With no output schema, the description appropriately covers the return value and its two formats, which is the key unknown. Minor gaps remain (error/missing-article behavior, language fallback is only in the schema), but for a simple single-record read it is largely complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the enum by explaining the semantic difference between the two formats – text is the readable default with blocks expanded, HTML is intended for editing – which is real guidance the schema does not provide.

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

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

States a specific verb and resource ('Read one article') and adds what the result looks like (plain text vs HTML). It is clearly distinct from list_articles/search_knowledge_base by implication, though it never names a sibling to sharpen that boundary.

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: the word 'article' plus the 'from search_knowledge_base or list_articles' hint in the schema suggests this is the follow-up to a search. The description itself gives no explicit when-to-use or when-not guidance, and no prerequisite conditions.

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

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

The annotations already establish that this is a read-only, open-world operation. The description adds relevant return-scope context by saying both published and draft articles are included, but it does not describe structure, permissions, or pagination.

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?

It is a single front-loaded sentence with no wasted words. The key resource and return scope are stated immediately.

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

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

For a simple one-parameter read tool with annotations covering safety and full schema coverage, the description is largely complete. It explicitly notes the inclusion of published and draft articles, though without an output schema it could say slightly more about the returned shape.

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

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

Schema description coverage is 100%, and the categoryId parameter is already documented as coming from list_categories. The description adds no additional parameter meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description gives a specific verb and resource ('Get one category') and adds the useful scope detail that published and draft articles are included. It is clearly distinguishable from list_categories and get_article, though it does not explicitly name those 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?

Usage is implied by 'one category' and by the sibling list_categories, but the description does not explicitly state when to use this tool versus alternatives or mention prerequisites beyond the schema's reference to list_categories.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact — 'Returns compact rows' — signaling lean payloads, but says nothing about pagination behavior, total counts, ordering, or how filters combine (AND vs OR).

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

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

Two short sentences, zero filler, filters front-loaded and the return-shape note trailing. Nothing could be removed without losing 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 read-only, fully-documented, zero-required-parameter list tool with annotations covering safety, the definition is nearly sufficient. The small remaining gap is sort order and how multiple filters compose, which an agent may need to predict results.

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

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

Schema description coverage is 100%, so every parameter is already documented, including enum semantics for accessibility and the categoryId cross-reference. The description only restates the filter names and loosely maps 'visibility' to the accessibility parameter; 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 ('articles') and enumerates the filter dimensions, so the agent knows exactly what the tool does. It does not, however, distinguish itself from plausible siblings like search_knowledge_base or find_stale_articles, which also surface 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?

No guidance on when to choose this over search_knowledge_base (keyword/relevance retrieval) or find_stale_articles (a specialized subset). The filter list implies a browsing use case, but that is inference rather than stated guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the returned field set, but is silent on whether results are flat or hierarchical, whether uncategorized/private categories appear, and whether the list is paginated — meaningful gaps for a listing call whose shape depends on hierarchy.

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 sentence, front-loaded with the verb and resource, and the parenthetical return-field list is dense with useful information. No filler or redundancy.

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

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

For a read-only listing tool with one optional parameter and no output schema, listing the returned fields is the right kind of compensating detail. Minor gaps remain around hierarchy representation and language behavior, but nothing essential to invoking 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% with a single optional parameter, so the baseline of 3 applies. The description does not mention the language filter at all, so it adds nothing beyond the schema's 'Language code' text.

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

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

States a specific verb (List) and resource (knowledge base categories) and enumerates the returned fields, which makes it clearly distinct from the singular sibling get_category. It does not explicitly name siblings, so sibling differentiation is only implicit.

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: an agent can infer this is the bulk-retrieval option versus get_category, but the description never says when to prefer this over search_knowledge_base or how the optional language parameter changes results. No exclusions or prerequisites 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description contributes useful ordering semantics ('newest first'), but leaves 'recent' undefined — no retention window, no default time span — which is the key behavioral unknown for an activity feed.

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 compact sentence with the resource scoping and the sort order both front-loaded; nothing is wasted. It is arguably under-specified rather than over-long, which is a separate dimension.

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?

All four parameters are optional and fully documented, all parameters optional, and no output schema exists, so the description only needs to convey what comes back and in what order — which it does. The remaining gap is the undefined lookback window for 'recent', which an agent auditing activity would reasonably want.

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

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

Schema coverage is 100% with per-parameter descriptions for page, limit, actionType and trackableType, so the baseline is 3. The description's 'created, edited or published' loosely gestures at actionType values but never connects to the filters, so it adds little beyond the schema (and 'publish' doesn't match the documented create/update/destroy examples).

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 names the resource (knowledge base activity log) and its contents precisely — who created, edited or published what — which is enough to distinguish it from list_articles and search_knowledge_base. It leans on the name's 'list' verb rather than restating it, but the parenthetical makes the payload unambiguous.

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

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

The audit-style framing ('who created, edited or published what') implies when to reach for it, but there is no explicit when-to-use, no mention of alternatives such as search_knowledge_base, and no exclusion conditions. Usage is inferable 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?

The annotations already establish readOnlyHint=true and openWorldHint=true, so the safety profile needs no restating. The description does add real value by disclosing that results are truncated ('a short text sample'), which prevents an agent from quoting a snippet as an answer. It says nothing about result caps, pagination, or ranking, so it goes beyond annotations only modestly.

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, each doing distinct work: scope, return shape, follow-up. The core capability is front-loaded in the first clause with no preamble or 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 carries the burden of explaining what comes back, and it does ('matching articles with a short text sample'). It also supplies the follow-up step needed to act on those results. Slightly incomplete in that result count, ordering, and empty-result behavior are unstated for a 2-parameter search 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 parameters are documented in the schema with examples ('reset password', 'SSO setup') and the categoryId scoping constraint. The description adds no semantics beyond that, 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 ('Full-text search across the Helpjuice knowledge base') and pairs it with the return shape ('matching articles with a short text sample'). That is enough to distinguish it from list_articles (enumerating) and get_article (fetching one full article) without opening a schema.

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

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

Gives an explicit routing rule: use get_article to read the full answer before quoting, which tells the agent this is a discovery step, not an answer source. It stops short of naming exclusions, e.g. when to prefer list_articles or find_stale_articles, and gives no guidance on broadening or narrowing a query that returns nothing.

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=false, idempotent=true, destructive=false, so safety is covered. The description adds genuinely new behavioral context: that unspecified fields are preserved (partial merge), and that body format depends on prior retrieval via get_article. No mention of permission requirements or what happens to published state transitions.

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 action and scope, followed by the merge semantics and the prerequisite read. 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?

Reasonable for a 6-parameter mutation, but gaps remain: the title/summary-to-name/description mapping is unresolved, no output schema or return-value hint is given, and consequences of toggling 'published' are not described. Adequate but not complete.

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

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

With only 33% schema description coverage, the description partially compensates by naming the updatable fields. However, it uses 'title' and 'summary' while the schema parameters are 'name' and 'description', leaving a mapping ambiguity that the agent must infer, and articleId provenance is only covered in the schema.

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

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

States a specific verb and resource ('Update an article') plus the exact fields it can change, so the operation is unambiguous. It does not explicitly differentiate itself from siblings like create_article or delete_article, but the implicit read-then-write framing helps.

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 workflow prerequisite: read the article first with get_article(format='html') when editing the body, and clarifies partial-update semantics ('Only the fields you pass are changed'). It stops short of naming when not to use it (e.g., use create_article for new content).

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