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

Adds substantial context beyond the annotations: Bearer auth from ABS_API_TOKEN, self-hosted Audiobookshelf only, writes gated by confirm=true AND ABS_ALLOW_WRITES=true, dry-run sends nothing, and destructive/credential actions (delete, scan, match, purge, restore, API key, password, settings) get an extra preview warning. This is consistent with destructiveHint=true and non-idempotent writes rather than contradicting them.

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

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

Dense but front-loaded: environment/auth constraints first, then write-gating and dry-run semantics, then the action list. The opening sentence ('covers the authors toolset (5 operations)') is slightly meta and the count is arguably off since help is a sixth enum value, but there is little wasted text.

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

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

With no output schema and 6 parameters including nested body/query/params objects, the description covers the operational essentials an agent needs: auth, write safety, dry-run default, and how to discover per-action parameters via help. It omits which path params each action requires (e.g., id for get_by_id), though help/target mitigates that.

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 body, query, params, target, and the confirm const semantics. The description restates the confirm/help semantics rather than adding new syntax, 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?

Names the resource (authors toolset) and enumerates the concrete operations (delete_by_id, get_by_id, patch_by_id, post_match, delete_image), which is far beyond restating the name. It does not explicitly contrast with sibling tools like abs_items or abs_search, so 4 rather than 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?

Gives actionable routing: use action 'help' with target to inspect one action's parameters, omit confirm for a dry-run preview, and only execute by setting confirm to boolean true. It does not explain when an agent should pick an author operation versus a sibling toolset, but within the tool the when-to-use guidance 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?

Goes well beyond the annotations by naming the credential source (Authorization Bearer from ABS_API_TOKEN), the second env gate ABS_ALLOW_WRITES, and the fact that omitting confirm sends nothing at all — a genuinely non-obvious safety behavior. It also flags which action classes (delete, scan, match, purge, backup restore, user, API key, password, settings) emit an extra warning in the preview, which is real predictive context the annotations do not 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?

Front-loads scope, then auth, then the confirm/dry-run contract, then the action list — a sensible order with almost no filler. The two long enumerations (nine actions and ten warned action classes) are dense and slightly run-on but each item carries distinct 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 six-parameter multi-action dispatcher with no output schema, this covers auth, environment gating, dry-run semantics, destructive-action warnings, the action inventory, and the self-documenting help path. What it omits — the individual action contracts — is intentionally delegated to 'action help with target', which is a reasonable design rather than a 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 coverage is 100%, so baseline is 3; the description adds workflow meaning by pairing confirm with the dry-run/execute distinction and pairing target with the help action. The ABS_ALLOW_WRITES dependency for writes is parameter-relevant context absent from the schema, though the confirm behavior itself is largely restated from 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?

Declares itself as the collections toolset for Audiobookshelf and lists all nine operations, which lets an agent separate it from abs_authors, abs_libraries, abs_items and the other siblings. The operation names (get, post, patch_by_id) are generic REST verbs rather than descriptive of what they do to a collection, so the resource scope is clear but the per-action semantics are not.

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

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

Gives concrete routing rules: 'action help with target returns one action's parameters', 'Omit confirm for a dry-run preview', and writes require both confirm=true and ABS_ALLOW_WRITES=true. It excludes unsupported deployments ('Self-hosted Audiobookshelf only') but never contrasts with sibling tools, so an agent still has to infer that collections are distinct from libraries or items.

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 Bearer token source, self-hosted-only scope, the double gate on writes (confirm plus env flag), that a dry run sends nothing, that destructive/credential actions add an extra warning in the preview, and enumerates which of those actions are dangerous. This is exactly the context annotations cannot carry and is consistent with destructiveHint=true and readOnlyHint=false.

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 domain, auth, and scope, then the write-safety rules, then the action list. Dense but every sentence carries operational information; the destructive-action enumeration is a bit of a list but pays for itself in preview expectations.

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 multi-operation dispatch tool with nested objects, no output schema, and 100% schema coverage, the description supplies the missing pieces: auth, host scope, write gating, dry-run semantics, and a help action for per-action parameter discovery. An agent can invoke it correctly without opening any sibling definition.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds value by explaining the action+target pairing for help and the runtime dependency (ABS_ALLOW_WRITES) that gates confirm. It adds little about body/params beyond what the schema already says, keeping 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?

Names the resource domain (genres), states the toolset size (3 operations), and enumerates the actions (delete_by_id, get, post_rename), which distinguishes it from siblings like abs_authors or abs_tags. The verbs stay at the action-name level rather than describing what each action retrieves or mutates, so it is clear but not maximally specific.

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

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

Gives concrete invocation rules: use action=help with target to learn an action's parameters, writes require confirm=true plus ABS_ALLOW_WRITES, and omitting confirm produces a dry run. It does not explicitly route the agent away from sibling toolsets, but for a namespaced CRUD wrapper that is largely self-evident.

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

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

Annotations already mark it destructive/non-readonly, and the description adds substantial context: Bearer auth from ABS_API_TOKEN, self-hosted-only scope, the write gate requiring ABS_ALLOW_WRITES, dry-run preview behavior, and a specific list of actions that trigger extra warnings (delete, scan, purge, backup restore, key/secret actions). This materially exceeds what the annotations convey.

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

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

Front-loads the toolset scope and auth, then adds behavioral constraints and the action list. Dense but every sentence carries information; the long action enumeration is necessary for a dispatcher 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?

With no output schema and a mutation-capable tool, the description covers auth, dry-run safety, destructive warnings, help discovery, and the full action set. Return-value format is left undescribed, a minor gap for a complex 18-action router.

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 usefully clarifies confirm semantics (only boolean true accepted, string rejected, omit for preview) and the target/help relationship, adding meaning beyond the schema.

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

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

States it 'covers the items toolset (18 operations)' for Audiobookshelf and enumerates all actions, making the resource domain clear. It's distinguishable from siblings like abs_authors or abs_series by the explicit action list, though the top-line framing is broad.

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?

Explains the help+target pattern to discover per-action parameters, and clearly states that writes require confirm=true plus ABS_ALLOW_WRITES=true while omitting confirm yields a dry-run. No explicit when-to-use-this-vs-sibling guidance beyond the resource domain, but operationally strong.

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

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

Beyond the annotations, the description discloses the auth mechanism (Bearer from ABS_API_TOKEN), a hosting constraint (self-hosted only), the dual gate required for writes (confirm=true plus ABS_ALLOW_WRITES=true), the dry-run-by-default behavior when confirm is omitted, and that destructive/credential actions emit an extra preview warning. That is exactly the kind of operational context annotations cannot convey.

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

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

The opening sentences are well front-loaded with the highest-value facts (auth, write gating, dry-run). However, the trailing list of 26 actions is a flat restatement of the enum already present in the schema, adding length without adding 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?

For a six-parameter destructive dispatcher with nested objects and no output schema, the description covers auth, safety gates, preview behavior, and parameter discovery. The gap is that it gives no hint about per-action return shapes or which actions are reads versus writes, leaving the agent to call help per action.

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 per-field documentation already does the heavy lifting. The description still adds value by explaining the help/target discovery loop and the confirm-omission dry-run semantics, though it says nothing about the body, query, or params shapes beyond what the schema already declares.

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 toolset (Audiobookshelf libraries), states it hosts 26 operations, and enumerates every action, so an agent knows the exact scope. It does not, however, distinguish this tool from siblings like abs_authors, abs_search, abs_series, or abs_stats, several of which appear to overlap with actions listed here (get_authors, get_search, get_series, get_stats).

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 strong procedural guidance for the call pattern: action help with target to discover per-action parameters, and a dry-run-then-confirm workflow for writes. But it never says when to choose this tool over the sibling tools that cover authors, search, series, and stats, which is the main routing decision an agent faces.

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 destructiveHint/openWorldHint annotations, the description discloses the auth mechanism (Authorization Bearer from ABS_API_TOKEN), the self-hosted-only constraint, the confirm/dry-run protocol, and that destructive or credential actions (delete, scan, purge, backup restore, API key, password, settings) emit an extra warning in the preview. The schema also confirms secrets are redacted in output. This is substantive context an agent cannot get from annotations alone.

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 opening sentences are well front-loaded with auth, scope, and the dry-run/confirm protocol, but roughly half the text is a flat enumeration of 23 action names that duplicates the input schema's enum verbatim. That list earns no new information and dilutes an otherwise tight description.

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 multi-operation dispatch tool with 6 parameters, no output schema, and destructive annotations, the description covers auth, runtime gating, dry-run behavior, and discovery via 'help' — enough for correct invocation. It stops short of describing return payloads or confirming that 'help' output is the canonical per-action contract, which would fully close the loop.

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 beyond the schema: that 'target' is the help lookup key, that 'params' are Express path parameters, and that confirm must be the boolean true while false and the string 'true' are rejected. That said, it does not explain which path parameters each action requires or what goes in body vs. query, leaving per-action parameter binding to the help action.

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 it exposes the 'me' toolset with 23 actions against a self-hosted Audiobookshelf instance, and enumerates every action, so an agent knows exactly what surface it covers. It does not explicitly contrast itself with siblings like abs_sessions or abs_items, which expose similar verbs on different resources, so an agent must infer that this one is scoped to the authenticated user.

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

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

It gives concrete selection guidance: use action 'help' with a target to discover an action's parameters, and writes require confirm=true plus ABS_ALLOW_WRITES=true. Omitting confirm yields a dry-run preview, which is a clear when-not-to-execute rule. What is missing is explicit routing between this tool and the sibling tools that overlap in verbs (sessions, stats, items).

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 destructive, non-idempotent, open-world behavior, and the description adds important context: Bearer auth, self-hosted-only restriction, explicit write gating, dry-run preview that sends nothing, and extra preview warnings for destructive or credential actions. The warning list includes actions not present in this tool's enum, such as scan and purge, which slightly reduces precision.

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 definition is mostly front-loaded and appropriately sized: purpose, auth, write gating, and preview behavior come before the action list. The destructive/credential warning sentence enumerates operations outside this tool's action enum, which is unnecessary noise for abs_playlists.

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 10-action facade with no output schema, the description covers auth, write gating, dry-run behavior, and the help mechanism. It does not explain what individual actions do, such as get versus get_by_id, post versus post_collection or post_item, or batch add versus batch remove, so an agent must invoke help before selecting confidently.

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 action, target, confirm, params, query, and body. The description mostly duplicates the confirm and help+target semantics and adds little detail about body, query, or params beyond what the schema provides.

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

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

The description states that this tool covers the playlists toolset and lists its operations, making the resource clear and distinct from sibling tools like abs_items or abs_collections. However, 'covers' is somewhat loose, and generic action names such as get, post, and patch_by_id are not individually explained.

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 clear operational guidance: use action help with target to inspect an action's parameters, set confirm to true for writes, omit confirm for a dry-run preview, and requires ABS_ALLOW_WRITES=true. It does not explicitly say when to choose this tool versus each sibling or which action fits which playlist task, but the playlist scope and write-preview rules provide strong 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?

Despite annotations already declaring destructiveHint=true and readOnlyHint=false, the description goes further: it names the auth mechanism (Bearer ABS_API_TOKEN), the environment gate (ABS_ALLOW_WRITES=true), the dry-run-by-default behavior ('sends nothing'), and the specific set of actions that trigger extra warnings (delete, scan, match, purge, backup restore, user changes, API key create/revoke, password, settings). This is the kind of safety context annotations cannot convey.

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

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

Purpose is front-loaded in the first clause, followed by auth, write protocol, and the action inventory. Nothing is padded, though the confirm/dry-run explanation duplicates the schema's own description, a minor 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 6-parameter action dispatcher with no output schema, the description covers auth, write gating, dry-run behavior, destructive-action warnings, and per-action help discovery. The main remaining gap is that the return shape is undocumented, which matters here since no output schema exists to compensate.

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 restates the confirm semantics that the schema already documents verbatim and doesn't add structure for body/query/params beyond what the schema says. The only marginal addition is the ABS_ALLOW_WRITES prerequisite, which is environmental rather than parameter-level.

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 ('podcasts toolset' in Audiobookshelf) and enumerates all 12 actions, so the agent can tell it apart from siblings like abs_items, abs_series, or abs_playlists. The framing verb ('covers the podcasts toolset') is generic, but the action list supplies the concrete specificity.

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

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

It states the environment constraint ('self-hosted Audiobookshelf only'), points the agent to 'action help with target' for per-action parameter discovery, and spells out the write path (confirm=true plus ABS_ALLOW_WRITES=true) versus the dry-run default. It doesn't explicitly say when podcast tasks should route here instead of a sibling, but the resource scoping makes that largely self-evident.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds useful context beyond annotations: Bearer auth from ABS_API_TOKEN, self-hosted Audiobookshelf only, and the help-with-target mechanism. It does not explain what each action returns, pagination, or rate-limit behavior.

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

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

The description is compact and mostly front-loaded, moving from scope to auth to environment to actions without filler. The opening 'covers the search toolset' is slightly imprecise but does not waste much space.

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

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

For a tool with five parameters, nested objects, and six actions, the description provides the essential auth/environment constraints and a discovery path via the help action. It does not explain what each action does or how to distinguish this tool from overlapping siblings, leaving meaningful gaps for an agent selecting the right 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 action, body, query, params, and target. The description adds only one semantic detail beyond the schema: action=help with target describes that action's parameters. Baseline 3 is appropriate.

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

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

The description enumerates the six actions (get_authors, get_books, get_chapters, get_covers, get_podcast, get_providers) and mentions the help action, so the resource scope is knowable. However, labeling this a 'search toolset' is misleading because the actions are all retrieval/get operations, and it does not differentiate from sibling tools like abs_authors, abs_podcasts, or abs_items that appear to cover overlapping resources.

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 is given on when to use abs_search versus sibling tools such as abs_authors or abs_podcasts, nor when to prefer one action over another. The auth and self-hosted constraints are prerequisites, not usage-selection 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?

The description adds substantial behavior beyond the annotations: authentication source, self-hosted-only constraint, write gating via confirm=true plus ABS_ALLOW_WRITES=true, and the dry-run default when confirm is omitted. These are important operational details that an agent would not infer from the annotations alone.

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 compact and front-loaded: resource scope, auth, hosting constraint, help behavior, write/dry-run rules, and action enumeration. Every sentence carries operational information without 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 six-parameter wrapper with no output schema, the description covers the critical calling constraints: auth, action help, write confirmation, dry-run behavior, and available actions. It stops short of describing return values or error behavior, but the operational essentials are present.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description still adds meaningful semantics for confirm (must be boolean true; omit for dry-run; false and string true are rejected) and for target with action help, exceeding the schema baseline.

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

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

The description states that abs_series covers the series toolset with exactly two operations, get_by_id and patch_by_id. This distinguishes it from sibling resource tools such as abs_items and abs_authors, though it does not explicitly gloss what each operation does beyond the action names.

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 clear operational context: Authorization Bearer from ABS_API_TOKEN, self-hosted Audiobookshelf only, and how to use action help with target. It also states the write confirmation rule and that omitting confirm produces a dry-run preview. It does not explicitly route between sibling tools, but the series scope 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 declare readOnlyHint=false and destructiveHint=false but say nothing about the write gate, auth, or hosting constraint; the description supplies all three (Bearer from ABS_API_TOKEN, self-hosted Audiobookshelf only, confirm-plus-env-var required, omission = no-op preview). It stops short of describing what post_session_close actually does to a session or whether repeats are safe, despite idempotentHint=false.

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?

Five dense sentences, each covering a distinct concern (scope, auth, hosting, help/parameters, write safety, action list) with no filler. Front-loading is decent, though the action enumeration would be more useful at the top than as a trailing clause after the confirm rules.

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 six-parameter, nested-payload gateway with no output schema, the description covers the things most likely to cause a failed or unsafe call: authentication, hosting environment, dry-run default, and the full action set. It omits per-action path-parameter expectations (e.g. which id 'get_session' needs) beyond pointing at 'help', which is a real but manageable 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 all six parameters are documented in the schema itself, establishing a baseline of 3. The description adds only one genuinely new semantic — that 'target' is meaningful solely when action=help — and otherwise restates the confirm contract already spelled out 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?

Opens by naming the resource domain (sessions toolset) and enumerates the four concrete operations (get, get_open, get_session, post_session_close), which lets an agent separate it from siblings like abs_items or abs_playlists. It never states in plain language what a 'session' is (an active playback session), so an agent must infer this from the action names.

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 operational guidance: use 'action help' with a target to get an action's parameters, writes require confirm=true plus ABS_ALLOW_WRITES=true, and omitting confirm yields a dry-run. It does not say when to prefer abs_sessions over a sibling such as abs_items when looking for playback state, so selection guidance stops at the domain boundary.

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, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds real value with the auth requirement (Authorization Bearer from ABS_API_TOKEN) and the 'self-hosted Audiobookshelf only' constraint. It says nothing about what the stats results look like or rate/scope 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?

Four short sentences, front-loaded with scope and auth, no filler. Slightly telegraphic in places ('Self-hosted Audiobookshelf only.' reads as a fragment) but nothing that wastes space.

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 5-parameter wrapper with nested objects and no output schema, the description should at least signal what each action needs (params like id) and what it returns. It covers auth and the help mechanism but leaves the agent to infer per-action parameter requirements from the schema alone.

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/query/params/target are already documented in the schema and baseline 3 applies. The description only clarifies the help+target pairing, repeating what the schema's target description already says.

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 it covers the Audiobookshelf stats toolset and enumerates the two real operations (get_server, get_year) plus help, which distinguishes it from siblings like abs_items or abs_libraries. Slightly muddied because get_server does not obviously read as a 'stats' operation, and the '2 operations' count excludes help.

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 one concrete usage rule — 'action help with target returns one action's parameters' — which is genuinely useful for discovery. However, it never says when to pick get_year vs get_server, nor when to use this toolset at all versus other abs_* 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?

With annotations already marking the tool destructive and non-read-only, the description adds meaningful behavior: Bearer auth from ABS_API_TOKEN, writes requiring confirm=true plus ABS_ALLOW_WRITES=true, and a dry-run preview that sends nothing. It also warns that destructive or credential actions get extra preview warnings, though the listed warnings include operations outside this tool's three actions and do not spell out delete/rename side effects.

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

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

The description is front-loaded with scope, auth, and write behavior, and most sentences carry operational value. The long warning enumeration is somewhat overbroad for a three-action tool and adds noise, but it does not obscure the key instructions.

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 multi-action dispatcher with 100% schema coverage and no output schema, it supplies the important auth, write-gating, dry-run, and help-discovery context. It still leaves the concrete semantics of get, delete_by_id, and post_rename unexplained, relying on the help action for per-action details.

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 action, target, confirm, body, query, and params; the description mostly repeats the action enum and help/confirm behavior. The one meaningful addition is the ABS_ALLOW_WRITES requirement tied to confirm, but action-specific parameter mappings are left to the help action.

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?

Identifies the resource as the Audiobookshelf tags toolset and enumerates the three operations (delete_by_id, get, post_rename), so the agent can distinguish it from abs_authors, abs_items, and other siblings. However, it does not describe what each operation actually does beyond the action names, keeping it short of a fully self-explanatory purpose.

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 invocation guidance for help, dry-run, and write paths: action help with target returns parameters, writes need confirm=true, and omitting confirm produces a preview. It states auth and self-hosted constraints, but does not say when to choose abs_tags over sibling tools such as abs_items or abs_search, so alternatives remain implied.

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