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

Annotations mark the tool as non-read-only but non-destructive, and the description aligns by making clear which actions mutate (create, update, import_url, approve, reject) and that snippet_update changes only given fields. The 'Undocumented API' note is a useful caveat, but nothing is said about permissions, whether rejected/updated data is recoverable, or error behavior — and no annotation-supplied context is extended.

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?

A one-line scope statement followed by a scannable action list where every bullet earns its place by pairing an action with its parameters. Front-loaded and free of 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 nine-action tool with 11 parameters and no output schema, the description covers the action surface and gives brief return hints ('short preview', 'full content', 'show whether FAQ learning is on'). The remaining gap is that the 'Undocumented API' caveat is stated without any guidance on constraints or failure modes across those actions.

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 defines all 11 parameters; the description still adds real value by mapping parameters to actions (snippet_create(title, content, ...), faq_approve(id, ...), learning_get() with none), which the flat schema cannot express. It marks optional slots with ellipses but does not explain which optional fields each action honors.

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 opening sentence names a specific verb and resource — managing the snippets AI assistants answer from plus reviewing FAQ suggestions — and the action list makes each verb+resource concrete. It falls short of a 5 because it never distinguishes these snippets from the knowledge-base content handled by siblings like libredesk_articles and libredesk_help_center, which is where confusion is most likely.

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 per-action breakdown (snippet_get for one item's full content vs snippet_list for a preview, faq_approve vs faq_reject, partial update vs create) implies when to pick each action. However there is no explicit guidance on when to use this tool instead of the sibling knowledge/article tools, and no prerequisites or exclusions 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 only declare readOnlyHint=false and destructiveHint=false, and the description consistently adds real behavioral nuance beyond that: create makes a 'draft', update changes 'only the given fields', sync 'writes new ids back' and 'Never publishes', linkable filters by locale. This is genuinely useful for a mixed read/write dispatcher. It stops short of stating permission or rate-limit characteristics for the mutating actions.

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 'Undocumented API' caveat, then a scannable action list where each entry is a single high-density line. No filler sentences; length is proportional to eleven actions.

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 20-parameter dispatcher with no output schema, the description covers what each action does and partially what it returns (content vs no content, translations, why articles are hidden). A few return-shape gaps remain — e.g. what list's article summaries contain or what sync reports for skipped files — but nothing that would cause a misinvocation.

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 action list adds context the flat schema cannot: it binds help_center_id to list/visibility/linkable, collection_id to create/move/list, and shows the shape of reorder's order map. It does not mention format or dry_run, though the schema documents both well.

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 (knowledge base articles, markdown I/O) and then enumerates all eleven actions with a verb+object signature for each, e.g. 'move(id, collection_id): Move an article to another collection of its help center'. An agent can distinguish list vs get vs visibility vs sync 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?

Each action line explains the condition that selects it: list returns articles 'without content', get returns 'content and translations', visibility reports 'which articles AI assistants can use, and why the others are hidden', sync handles local .md files. What is missing is routing against the siblings — nothing says to use libredesk_publish to publish or libredesk_delete for removal, so the agent must infer that this tool never publishes or deletes.

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 destructive=true, but the description goes further and names exactly what each delete destroys: a help center takes all its collections and articles, a collection takes its articles, translations survive an article delete, and assistants stop using a snippet. It also flags 'Deletes cannot be undone' and 'Undocumented API', which is information no structured field carries.

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 front-loaded sentences carry the irreversible and undocumented warnings, followed by a compact action list where every line adds a distinct fact. 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?

For a destructive, undocumented API with no output schema, the description covers irreversibility, cascade scope, and per-action parameters well. What it omits is whether a success response or confirmation is returned and what error behavior to expect when the target is missing or still referenced.

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 the pairing the schema does not state: collection_delete consumes both help_center_id and id, while article_delete and snippet_delete take only id. The 'profile' parameter is still unexplained, but the action-to-parameter mapping is a genuine addition.

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 the exact four resources affected, then breaks each down by action name and effect. An agent can tell immediately this is the destructive counterpart to the sibling help-center/article tools 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?

Each action line gives a clear condition for choosing it (help_center_delete vs collection_delete vs article_delete vs snippet_delete), which is the real selection problem for a multi-action tool. It stops short of naming when NOT to use it or pointing to siblings like libredesk_help_center for non-delete operations, and states no permission prerequisites.

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

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

Annotations mark it readOnlyHint=false / destructiveHint=false, but the tool bundles read actions (list, get, tree, insights) with mutating ones (create, update, collection_reorder) under a single non-readOnly hint, and the description never disambiguates which actions write. It does add useful behavioral detail like 'Change only the given fields' and flags the API as undocumented, but omits side effects such as custom_domain pointing public traffic at a new origin.

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 a one-line purpose, then a scannable action digest where each bullet earns its place. 'Undocumented API' is a useful caveat, though the ellipses shorten lines at the cost of the parameter-to-action mapping.

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-action, 22-parameter tool with no output schema and no per-action schema discrimination, the description underspecifies which optional parameters belong to create versus update versus collection_create. Return shape is only hinted at ('with all settings and theme'), and there is no coverage of mutation side effects or failure modes.

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 would be 3, but the action signatures (tree(id, ...), collection_reorder(help_center_id, order)) map parameters to the actions that accept them — information the flat schema cannot convey since it has no per-action discrimination. The '...' placeholders leave the full mapping incomplete, keeping it below 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?

The first sentence names the resource domain (help centers and their collections) and the action enumeration makes the tool's scope concrete enough to separate it from libredesk_articles and other siblings. It stops short of explicitly pointing at a sibling for article editing, which is the only missing piece for 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?

The per-action list implies when each action applies (e.g. tree vs get, collection_reorder vs collection_update), and 'Change only the given settings' signals partial updates. However, there is no explicit guidance on choosing this tool over libredesk_articles or libredesk_lookup, and no stated prerequisites such as needing an existing help center before creating a collection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description stays consistent with them. It adds genuine value beyond annotations by disclosing the fields each action returns (id/name/email for agents, channel and enabled state for inboxes), and even flags agents() and teams() as [undocumented], which is honest about known gaps.

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?

A single scoping sentence followed by a scannable bulleted action list — front-loaded and free of filler. The [undocumented] tags are slightly unusual self-commentary but they are short and informative rather than noise.

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 listing the returned fields per action is exactly the compensating detail an agent needs, and it covers six of eight actions fully. The remaining gap is the custom_attributes(...) signature and the role of the profile parameter, both of which the description leaves to the 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 baseline would be 3, but the schema only labels the action enum as 'Action.' while the description spells out the meaning of all eight enum values and their outputs. It does not explain the profile or applies_to parameters, and the custom_attributes(...) ellipsis leaves its extra arguments unspecified.

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 opening sentence names a specific verb (look up) and resource set (ids of agents, teams, inboxes, settings), and the action list makes the scope concrete. It is clearly distinct from siblings like libredesk_publish, libredesk_delete and libredesk_articles, though it never states that differentiation 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 implied by the enumeration of actions rather than stated: an agent can infer it should call this before any id-taking operation, but nothing says when to prefer this over libredesk_articles or libredesk_help_center, and no exclusions or prerequisites 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 a non-read-only, non-idempotent mutation, and the description adds meaningful context: public visibility changes, AI usability coupling, and a per-conversation cost for FAQ learning. It stops short of covering permissions, reversibility of unpublishing, or rate limits.

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

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

The description is front-loaded with a high-level purpose and then a compact per-action breakdown, making it easy to scan. Minor redundancy exists, such as repeating that publishing changes what the public sees, and the 'Undocumented API' note is unexplained.

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 seven-parameter multi-action tool with no output schema, the description covers all four actions, their parameters, and the important side effects including cost and public visibility. The 'profile' parameter is not mentioned, and array handling for article/collection IDs is left to the 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 documents each parameter, including the overloaded 'id'. The description adds value by pairing each action with the parameters it actually uses, clarifying the multi-action dispatch.

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 opening sentence uses specific verbs and resources ('publish articles and collections, take help centers online or offline, switch FAQ learning') and the action list maps each operation precisely. It does not explicitly distinguish this tool from siblings such as libredesk_articles or libredesk_ai_knowledge, so it falls 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?

Each action is documented with its effect and the conditions under which it matters, such as publishing making an article public and AI-usable when ai_enabled is on. There is no explicit guidance on when to choose this tool over the related sibling tools, nor any stated exclusions or prerequisites.

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 the description reinforces this by flagging 'DESTRUCTIVE for DELETE: needs confirm' and tying confirm to prior user agreement — consistent, additive context. It also discloses that catalog with a domain returns field metadata, which is a behavioral detail not in the annotations. It says nothing about auth/profile selection or response shape, keeping it off 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?

One framing sentence followed by a two-bullet action list; the escape-hatch purpose and the catalog-first workflow are both front-loaded with no filler. Every line maps to something an agent must decide.

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 8-parameter, destructive, nested-object tool with no output schema, the description covers invocation and the delete guardrail but leaves the response shape entirely unexplained — an agent calling catalog or call has no idea what comes back. The profile parameter and its effect on auth are also unaddressed, which is a meaningful gap for a raw-API tool.

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

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

Schema coverage is 100%, so baseline is 3, and the description goes further by binding parameters to actions — method/path/confirm belong to call, domain belongs to catalog and additionally expands the returned field list. That action-scoping is genuine meaning beyond the flat schema, though it never touches body, query, or profile.

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 precisely ('raw API access') and enumerates the two verbs it supports (call, catalog), which is enough for an agent to understand this is an escape hatch for endpoints not covered by the dedicated siblings. It stops short of naming any sibling explicitly, relying on the phrase 'what other tools lack' to carry the distinction.

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?

'find the endpoint with catalog first' gives an explicit two-step workflow (discover, then call), and 'for what other tools lack' acts as a real exclusion telling the agent to prefer the dedicated tools. It does not say what to do when catalog returns nothing for a domain, but the core routing guidance is present.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that by disclosing what the tool actually reports (active profile, server acceptance of it, agent identity), which is important given there is no output schema. It omits whether the check performs a live network round-trip or how failures are surfaced.

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

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

Two short sentences with no filler; the what-it-reports clause is front-loaded and the trigger condition follows. Minor awkwardness in 'whether its server accepts it, as which agent' costs a point but 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 zero-required-parameter, read-only diagnostic with no output schema, the definition covers the essentials: what is inspected and when to reach for it. It could be stronger by sketching the shape of the result (e.g., profile name, server URL, auth state), but nothing critical to calling 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?

The single 'profile' parameter is fully documented in the schema (100% coverage), including that omitting it uses the default. The description's 'profile in use' gestures at the same concept but adds no syntax, format, or default behavior beyond what the schema already says. Baseline 3 applies when the schema carries the 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 ('Show') plus the exact facts reported: the profile in use, whether its server accepts it, and which agent identity is active. That is clearly a diagnostic/status tool, distinguishable from siblings like libredesk_articles or libredesk_publish, though the phrasing 'as which agent' is slightly ambiguous about what is being reported.

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 conditions: 'Call it on auth, profile or connection errors.' That gives an agent a concrete when-to-use rule. It stops short of naming when NOT to call it or pointing to any alternative diagnostic, but no sibling appears to compete for this role.

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