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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavior beyond them: detail=true silently caps limit at 25 and swaps the payload from progress fields to full item records. That cap-and-switch interaction is exactly the kind of hidden trait that prevents bad calls. It stops short of describing ordering or default page size.

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 what the agent gets, then the filters, then the mode switch. The parenthetical field list ('watched, viewCount, actors, collections…') is informative rather than filler, and nothing repeats the schema.

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

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

With no output schema, the description usefully sketches both return shapes and the truncation rule, which is what an agent needs to pick a mode. It doesn't state result ordering or that the default limit is 20, so it isn't fully airtight, but nothing critical 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 only 25%, so the description carries the burden — and it does: library is explained as a section filter, user as a Plex Home user selector, and detail's dual effect (cap + payload shape) is spelled out. Only `limit` is left to the schema, which supplies min/max/default, so the gap is minor.

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

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

Names a very specific resource — the next unwatched episode per in-progress show plus partially-watched movies — with the delivered value (progress position) stated up front. The 'in progress' scope naturally separates it from siblings like watch_history and now_playing without needing to name them.

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 through the optional narrowing flags ('optional library narrows to one section', 'user shows a Plex Home user's list'), but it never states when to prefer this over watch_history, now_playing, or search, nor any exclusions. An agent can infer the use case from the purpose but gets no routing 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 cover read-only/idempotent/non-destructive, so the description focuses on operation-specific traits: pagination, the detail=true interaction that caps limit at 25, and the extra fields that mode injects. It doesn't state the default page size or how ordering works, but the important behavioral rules are disclosed.

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 dense sentences, hierarchy mapping first, then the conditional flags, then the pagination constraint. No filler sentences and no repetition of structured fields beyond what adds 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 paginated list tool with no output schema, the description supplies hierarchy scope, pagination, the detail cap, and playlist gating. What's missing is only the default page size and any hint of returned record shape or ordering.

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 17% schema coverage, the description must carry the load, and it covers four of six parameters: detail (semantics plus the 25-item cap), playlist (the exact condition that requires it), and pagination via limit/offset. limit/offset defaults and the fields projection are left mostly to 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?

Names a specific verb+resource relationship and enumerates the concrete hierarchies it traverses (show→seasons, season→episodes, artist→albums, album→tracks, collection→items), which cleanly separates it from get_item, search, and get_extras.

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 container-type mapping tells an agent exactly which ratingKey kinds this applies to, and the playlist=true and detail=true notes give conditional guidance. It stops short of explicitly contrasting with get_item or search when a single known item is wanted.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuinely non-obvious behavior: local extras carry file paths while Plex streaming trailers return an empty paths value, which prevents misreading results as missing data.

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

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

Two tight sentences with no filler; the contents enumeration comes first and the paths caveat follows logically. Every clause earns its place.

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

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

With no output schema, the description sensibly discloses the one result nuance an agent would trip over (empty paths for streaming trailers). It is adequate for a single-parameter read tool, though a note on where ratingKey comes from would close the last 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?

The single parameter has 0% schema description coverage, so the description carries the burden. It tells the agent the key identifies one item, but does not explain what a ratingKey is or where to obtain it (e.g., from list_media or get_item), leaving a real gap.

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 and enumerates its contents (trailers, featurettes, behind-the-scenes, deleted scenes), which makes it unmistakable versus siblings like get_children or get_item. It does not explicitly contrast itself with a sibling, so it stops 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?

'for one item by ratingKey' implies you need a known item key, giving implicit context for use. But there is no explicit when-to-use guidance, no mention of how this relates to get_children or get_item, and no exclusions, so the agent must infer the routing decision.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), so the description correctly spends its words on what the read returns: file paths, codec, and size for movies, and watch progress ratios for shows. That return-shape disclosure is genuinely additive given no output schema exists, though error behavior for an unknown ratingKey is unstated.

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

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

Two short sentences, each carrying distinct information — the first establishes scope and input, the second splits return content by item type. No filler or restatement of the title.

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

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

For a one-parameter read tool whose annotations fully declare the safety profile, the description covers the essential return-content variation between movies and shows. The remaining gap is how a caller obtains a valid ratingKey, which is a real friction point in a 22-tool library where ids come from elsewhere.

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 0% for the single required parameter, so the description must compensate. It confirms ratingKey identifies exactly one item and that it accepts any media kind, but never explains the key's origin or format (the schema's ^\d+$ pattern is the only format hint) or that it must be exact.

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 metadata for one item by ratingKey") and scopes it to "any kind", which helps separate it from narrow siblings like get_children, get_extras, and library_stats. It stops short of naming a sibling outright, so differentiation is inferred rather than explicit.

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?

There is no statement of when to use this versus search, list_media, get_children, or person_credits. The only implicit guidance is that the caller must already hold a ratingKey, but the description never says to obtain one via search first or what happens when an id is stale.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description goes beyond them by disclosing the result shape (inLibrary flag, ratingKey presence/absence) and the ordering and pagination behavior, which an agent cannot get from annotations or the empty-coverage schema.

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

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

Three short sentences, front-loaded with what the tool returns, then the notable field semantics, then pagination. No filler and nothing repeated from the schema.

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

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

With no output schema, the description does the work of explaining the entry fields and null-ratingKey case, which is exactly what an agent needs to interpret results. Minor gaps remain around authentication as the server owner and the page-size ceiling.

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 0%, so the description must carry the burden; it names both parameters and their pagination role ('paginate with offset/limit'), which is real added meaning. However it omits the default page size of 50, the maximum of 100, and that offset is measured in entries from the newest title.

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

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

States a specific verb and resource with scope: the server owner's plex.tv watchlist, newest first. The read-only framing implicitly separates it from the sibling manage_watchlist, so an agent can tell which one mutates and which one lists.

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 read-only listing nature rather than stated. It never explicitly says 'to add/remove use manage_watchlist' or defines when an agent should reach for this versus get_item or search, leaving the read/write routing to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed world), and the description adds non-obvious behavior an agent could not infer: Plex bumps updatedAt during background refreshes so 'updated' may contain no-op entries, limit applies per bucket, and detail=true silently caps limit at 25. That is exactly the kind of caveat that prevents misinterpretation of results.

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?

Every sentence carries distinct information: bucket definitions, the overlap guarantee, the refresh caveat, the date format, the kind enum, the episode tip, the sibling alternative, and the two limit behaviors. It is front-loaded with the core purpose and no sentence is filler.

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

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

There is no output schema, so the description must convey return shape, and it does: two named buckets plus the extra fields detail=true adds (directors, actors, collections, summaries). Combined with the annotations and the per-parameter notes, an agent has everything needed to call it correctly and interpret the response.

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 0%, so the description must carry the load, and it does for four of five parameters: since accepts ISO or relative like '-7d', kind enumerates values and defaults to the library's own kind, limit is per-bucket, detail caps limit and adds fields. Only the 'library' parameter's default ('Movies') and limit's max of 200 are left to 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 combination ('what changed in a library since a cutoff') and immediately defines the two returned buckets ('added' vs 'updated') with the guarantee that they never overlap. This is enough for an agent to distinguish it from siblings like list_media or library_stats 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 concrete usage guidance: 'Use episode in a show library to see new episodes' and routes collection lookups to list_media with kind 'collection'. It lacks explicit when-not-to-use guidance versus siblings such as library_stats or watch_history, but the positive routing is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real behavioral context: enabling includeUserStats derives counts from watch history capped at the recent 10,000 plays, which is a data-scope caveat an agent could not get from the schema.

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

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

Two sentences, both front-loaded: the aggregate payload first, then the optional flag's effect and its data caveat. No filler and nothing repeated from the schema or annotations.

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

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

With no output schema, the description correctly enumerates what the response contains (totals, watched/unwatched, genre/decade/contentRating breakdowns) and explains the one non-obvious parameter. It falls short only on the 'user' and 'library' parameters, which remain unexplained.

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 only 33%: 'user' has a description, but 'library' and 'includeUserStats' have none. The description compensates well for includeUserStats (per-user play counts, 10,000-play window) but says nothing about the 'user' impersonation semantics or the 'Movies' default for 'library'.

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 ('Aggregate stats for a library') and enumerates the exact aggregates returned (totals, watched/unwatched counts, genre/decade/contentRating breakdowns). This clearly separates it from listing siblings like list_libraries and list_media, though no sibling is named 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 word 'Aggregate' and the includeUserStats note, which tells the agent when to flip that flag. There is no explicit 'use this instead of X' routing or statement of when not to use it, leaving the agent to infer that this is the summary tool versus the enumeration 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?

The annotations already establish readOnly, idempotent, non-destructive, and closed-world behavior, so the description appropriately focuses on return-value semantics. It adds genuinely useful context annotations cannot provide: that each section includes a key, whether a scan is running (refreshing), and a warning about misleading type values. It does not, however, discuss ordering or performance.

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

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

Four sentences are tightly packed with useful distinctions (libraryType vs type vs agent/scanner), and the core purpose leads. The agent/scanner aside is somewhat marginal, but it clarifies the source of the derived field rather than repeating the schema.

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

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

There is no output schema and no parameters, so the description must supply the shape of the result on its own. It names the key fields (libraryType, key, refreshing) and explains the most dangerous ambiguity (movie scanner vs Other Videos). Only minor omissions such as section titles or ordering keep it below a 5.

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 parameter semantics has no surface to cover. Rather than adding value here, the description spends its words on response fields, which is the baseline expected when no parameters exist.

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 gives a specific verb and resource: 'List all Plex library sections.' It also defines the meaning of the returned libraryType field, so an agent knows exactly what the tool enumerates. It stops short of contrasting itself with the sibling library_stats, so a 4 rather than 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 description says how to interpret the output ('libraryType is the field to read when deciding how to treat a library'), but it never says when to call this tool instead of library_stats, list_media, or search. Usage is implied by the broad enumeration rather than stated through explicit alternatives or exclusions.

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 safe read-only, idempotent profile, and the description still adds substantial non-obvious behavior: the watched filter means any-episode-played for shows while the record's watched field means fully watched, partially-watched items match both opposites, detail=true caps limit at 25, filters combine with AND, and kind=collection ignores other filters/sort. These are exactly the semantics an agent could get wrong.

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

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

Dense and long, but appropriate for a 22-parameter tool, and key defaults (watched='all', kind default) are front-loaded. Some sentences, especially the repeated mention of kind=collection, could be consolidated without losing meaning.

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

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

For a high-complexity listing tool with no output schema, the description does note what records carry (watched state, view counts, last-viewed) and warns about the detail cap. Pagination is mentioned via offset/limit. Coverage of the many remaining filters is the only real 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?

With only 36% schema coverage over 22 params, the description carries much of the weight, correctly defining watched, rated (internal 1-10 scale), sort=userRating putting unrated first, the detail limit cap, and collection-only mode. It leaves several filters (year, genre, decade, studio, country, maxDurationMin) unexplained beyond their names, so it is strong but not complete.

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

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

Opening sentence gives a specific verb and resource ('List items from any library') plus the scope of functionality ('rich filtering'). It is clearly distinct from siblings like library_stats or get_item, though it never names those alternatives to sharpen the 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?

The description explains how to use the filters (kind defaults, deep types via episode/track/album/season, collection for sections) but never states when to choose this over search, library_stats, or get_children. Usage is implied by the filter guidance rather than framed against alternatives.

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

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

Annotations already declare it read-only, idempotent, non-destructive and closed-world, so safety is fully covered. The description adds that ids are returned (useful for chaining, since there is no output schema), but says nothing about ordering, paging, or whether disabled/shared accounts are included.

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 returns and followed by the practical follow-up action. 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 input schema to explain, annotations covering the safety profile, and no output schema, the description carries the burden for return shape and does note it returns accounts with ids. Minor gaps (ordering, scope of accounts) keep it from full marks.

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 is 4; nothing about parameter semantics needs to be stated or could be added.

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?

"All Plex accounts on this server with ids" states a specific resource and its key output field, which is enough to distinguish it from the many listing siblings (list_libraries, list_media). It does not explicitly contrast with those siblings, but the resource is 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 second sentence gives a concrete downstream use: feed names or ids into watch_history's user filter. That is clear chaining guidance, though it never states when not to use this tool or what to do if only names are needed.

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 that delete removes ONLY the grouping and leaves items intact, that `kind` defaults to the library's kind and must match it, and that a partial failure during remove_items reports the keys already removed — a genuinely useful non-obvious recovery detail. Permissions requirements and whether create returns the new id are not covered.

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

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

Front-loaded with the verb set, then per-action requirements, then the failure caveat. Dense but zero waste — every clause is actionable.

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

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

A destructive multi-action tool with no output schema and no param descriptions; the description covers action semantics, required inputs, and the destructive scope. The notable omission is what comes back from create/add_items (e.g., the new collectionId), which an agent would need for chained calls.

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 0%, so the description must carry the load, and it does: it maps every parameter to the action(s) that require it and explains the `kind` defaulting/matching rule. It does not clarify ratingKeys being numeric strings or the 500-item cap, though the schema's pattern/maxItems partly cover that.

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 specific verbs (create, extend, prune, delete) against a concrete resource (a collection in a library) and enumerates the four actions the `action` enum supports. An agent can distinguish this from manage_playlist/manage_watchlist purely on the resource noun.

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 paired with the parameters it needs (create: title + library + ratingKeys; add_items/remove_items: collectionId + ratingKeys; delete: collectionId), which effectively tells the agent which action to pick for a given intent. It stops short of naming an alternative tool or an explicit when-not-to-use condition.

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

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

With destructiveHint=true already declared, the description still adds real value: 'deletes ONLY the playlist, never media' bounds the blast radius of a destructive operation, and the note that a partial remove_items failure returns an error naming the keys already removed is an unusual, genuinely useful disclosure about non-atomic behavior (consistent with idempotentHint=false). It stops short of stating permission requirements or whether create needs an existing library entry.

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 clauses, front-loaded with the verb list, each mapped to an action; no filler, no restatement of the title. The telegraphic style is dense but every fragment carries new 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 four-mode mutation tool with no output schema, the description covers inputs and destructive scope well but never says what create returns. An agent needs the new playlistId to subsequently call add_items/remove_items, and that linkage is unaddressed. Adequate but with a real gap for multi-step workflows.

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 0%, so the description carries the burden and mostly does: it assigns title+ratingKeys(+mediaType) to create, playlistId+ratingKeys to add/remove, and playlistId to delete, which supplies the conditional-requiredness the schema does not express beyond 'action'. It omits the 500-item cap on ratingKeys and the numeric-string pattern, but those are visible 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 with a specific verb set and a clear resource: create/extend/prune/delete a playlist, with the four operations named to match the action enum values. It does not distinguish itself from the sibling manage_collection or manage_watchlist, so the agent gets no explicit routing signal between the three '*manage*' tools.

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 parameter mapping ('delete: playlistId') implicitly tells the agent which action to pick for which input set, and the delete clause states a clear scope. However, there is no explicit 'use this when…' or exclusion pointing at manage_collection/manage_watchlist, so the usage boundary is left to inference.

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

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

Adds substantial behavior beyond the annotations: validation is all-or-nothing ('one bad key fails the whole call') and partial plex.tv failures produce an error naming the keys already changed — exactly what an agent needs to decide whether to retry. Annotations already cover idempotency and mutation safety, and nothing in the text contradicts 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?

Three sentences, each front-loaded with the highest-value fact: purpose, then validation atomicity, then failure semantics. No filler and no repetition of the title.

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

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

No output schema exists, yet the description explains failure behavior well; success-return shape (e.g. which keys were changed, count) is still unstated. For a 2-parameter mutation tool with annotations covering safety and idempotency, this is close to complete but leaves the success response to inference.

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 0%, so the description carries the burden and largely does: it defines ratingKey's meaning and validity preconditions (in a library, movie/show, has a Plex GUID) and makes the add/remove action explicit. It doesn't mention the 1–100 array bound or the numeric-string format, which remain schema-only.

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

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

States a specific verb pair (add/remove) and resource (server owner's plex.tv watchlist), plus the addressing mechanism (ratingKey). It is clearly the mutation counterpart to the read-only sibling get_watchlist, so an agent can route between them 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?

The scope constraint 'in the library' and the ownership constraint ('server owner's' watchlist) make the applicable context clear. It doesn't explicitly name get_watchlist as the read alternative or state when not to use it, so exclusions are left implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating the tool reports live playback state and enumerating the returned dimensions (user, item, player, progress), which the 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?

A single short sentence with zero filler, front-loading the temporal qualifier 'right now' and then the returned fields. Every element earns its place.

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

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

With no output schema, the description usefully sketches the return shape (user, item, player, progress) and the zero-parameter signature means there is little else to explain. A note on what is returned when nothing is playing would close the remaining 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The enumerated return fields add a little orientation but are not parameter semantics.

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

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

States a specific resource and temporal scope: what is playing on the server right now, plus the fields returned (user, item, player, progress). This clearly separates it from history-oriented siblings like continue_watching and watch_history, 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?

Usage is only implied by the phrase 'right now', which suggests a live snapshot versus historical queries. There is no explicit statement of when to call this instead of continue_watching or watch_history, and no prerequisites or exclusions 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral facts beyond them: results are paginated, and detail=true imposes a hard limit of 25 while enriching records with directors/actors/collections/summaries. It does not say what happens when detail=true is combined with a limit above 25, nor the default result ordering.

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

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

Four short sentences, front-loaded with the resource scope, followed by the usage example and then the operational caveats. Nothing is redundant and nothing is buried.

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 10 parameters, 10% schema coverage, and no output schema, the description supplies the key invocation facts: role, watched, pagination, and detail-mode limits. Gaps remain around sort/order/fields projection and the default return shape, but the essentials for a correct call 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 only 10%, so the description must carry the load. It does explain role, watched, and the detail/limit interaction well, but leaves sort, order, offset, fields, library (beyond the passing phrase 'within one library'), and the name parameter to the bare schema.

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

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

States a specific resource with scope: everything credited to a named person, restricted to one library and one role. That is clearly separable from list_media or search in substance, but no sibling tool is named, so the differentiation is implicit rather than explicit.

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 concrete example ('Scorsese films I haven't seen' = role:director, watched:'unwatched') shows exactly when this tool is the right call and how to express a natural-language request. It stops short of stating exclusions or naming the alternative (e.g. search) for across-library queries.

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

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

Annotations already declare read-only/non-destructive/idempotent, and the description adds genuinely new behavioral context: results are scoped to the Plex Home user so 'unwatched' is per-user, each pick is the same record shape list_media returns, and detail=true enriches the record for explanation. It does not cover edge behavior (e.g. what happens when fewer than count items match), which keeps it at 4.

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

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

Front-loaded with the core identity and the default pick count, then progressively more detail. Dense and largely waste-free, though the mid-sentence 'and so on' and the trailing detail clause make the last sentence slightly sprawling.

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 18 optional params and no output schema, the description does the right work: it describes the returned record shape and what detail adds, which an agent needs for follow-up reasoning. The remaining gap is behavior under sparse results (empty or short result sets) and the count cap, neither of which is mentioned.

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 low at 39% across 18 params, so the description has to compensate. It does add meaning for the important ones — count default of 3, the user-scoping of 'watched', detail's enrichment, and the combinability of genre/decade/maxDurationMin — but leaves rated, studio, country, library, addedSince, collection, contentRating and the lastViewed* params unaddressed. Partial compensation only.

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 ('N random items') plus the key qualifier that it uses the same filters as list_media, and labels itself as the 'just pick something' tool. An agent can immediately distinguish this sampling tool from the exhaustive list_media sibling 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?

It establishes the use case (pick something at random) and points at list_media as the filter reference, plus a concrete recipe: 'Combine watched=unwatched with genre, decade, maxDurationMin etc.' That gives clear context. It stops short of an explicit 'do not use this when you need the full list' exclusion, so it is not a 5.

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

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

Annotations already declare the operation non-read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the useful detail that the target is the *owner's* rating (not an aggregate) and that null clears it, but says nothing about auth requirements, response behavior, or what happens if ratingKey is invalid.

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 front-loaded sentence that carries the value range, the clear sentinel, and the target of the operation with zero filler.

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

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

For a simple two-parameter mutation with no output schema, the description covers the rating semantics but omits what `ratingKey` is and what the call returns or does on failure. Adequate but with a clear gap on the identifier parameter.

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 0%, so the description must compensate. It does explain the `rating` parameter's semantics (0-10 range, null to clear), but `ratingKey` is never explained — the schema only reveals a numeric-string pattern, not that it identifies the item. An agent is left guessing what this required key refers to.

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

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

States a specific verb pair (set/clear) and resource (owner's rating on an item), with the value range and the null-clears semantics. No other rating tool exists among the siblings, so no explicit differentiation is needed, but the description also doesn't tell the agent how this relates to the many item-scoped 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 only implied: an agent can infer it should call this to assign or remove a rating, but there is no explicit when-to-use, no prerequisite (e.g. must be the owner or authenticated user), and no note about how it interacts with set_watched or other item mutations.

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 why, and the description fills that gap precisely: it never modifies media files or metadata edits and never re-downloads metadata. It also discloses two behaviors invisible in the schema – the scan is asynchronous, and completion must be observed by polling list_libraries for a 'refreshing' state.

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

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

Front-loaded with the core action and scope, then safety, then the optional parameter, then async/polling. Every sentence carries information, though the parenthetical path hint and the polling instruction could be tightened into one clause without losing meaning.

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

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

For a two-parameter async action tool with no output schema, the description covers everything an agent needs: what it does, that it is safe despite write-like semantics, how to narrow scope, and how to verify completion. No important invocation detail is left to inference.

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 0%, so the description must carry the load, and it does for the non-obvious parameter: 'path' limits the scan to one server-side folder and points to get_item file.paths as the source of valid values. The required 'library' parameter is only implied by 'one library' – acceptable but the weaker half of the pair.

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 ('Trigger Scan Library Files') plus the resource scope ('one library') and the outcome ('Plex picks up added or removed files on disk'). No sibling tool does a scan, so the distinction is immediately clear from the name-plus-description pair.

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 the triggering condition ('picks up added or removed files on disk') and routes the agent to helpers for both pre- and post-steps (get_item file.paths for valid paths, list_libraries for polling 'refreshing'). It stops short of stating when a scan is unnecessary or which siblings to choose instead, so it is strong context rather than explicit when/when-not routing.

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

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

Annotations already cover read-only and idempotency, but the description adds real behavioral context: externalId lookups match ids Plex stores on every movie/show library and usually return one item or none, and the call reads every movie and show library in full so it costs a second or two on a large server. It does not address what happens when query and externalId are both supplied or both omitted.

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 and grouping are front-loaded, then routing guidance, then the externalId mode. The externalId sentence is long and comma-heavy, but every clause carries information an agent needs; no filler sentences.

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

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

For a read-only search tool with no output schema, the definition supplies scope, result shape, sibling routing, and the alternate id-lookup mode with its performance characteristic. Only the interaction between optional parameters and limit behavior is unstated, a minor gap.

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

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

Schema coverage is only 33%, and the description compensates well for externalId, explaining its format, matching basis and typical cardinality beyond the schema's one-line hint. However, 'query' matching semantics (exact, prefix, fuzzy) and 'limit' (default 20, capped at 50) are left entirely to the bare 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?

The definition states a specific verb and resource ('Global search across ALL libraries') and enumerates the media types searched, then adds what the output looks like ('hits grouped by type'). It also distinguishes itself from list_media/filtering siblings by making the cross-library scope explicit.

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

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

Explicit routing is given for each result type: person hits go to person_credits, item hits go to get_item. It also carves out a distinct mode (externalId instead of query) and states precisely when that mode applies — when you already hold an IMDb/TMDB/TVDB id.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false; the description goes beyond them by explaining why writes are non-idempotent ("marking watched also records a play") and by disclosing partial-failure semantics ("the error names the keys already marked"), which is genuinely useful for retry decisions. The gap is the unwatched path: it doesn't say whether removing watched status deletes existing play history.

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

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

Four short sentences, front-loaded with the action and scope, then progressively finer constraints and failure behavior. 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 two-parameter mutation with no output schema, the description covers the side effect and partial-failure reporting, which are the things an agent most needs. It stops short of stating what the successful response contains (counts vs per-key status) and of describing the unwatched side effect.

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 0%, so the description carries the burden; it does clarify that ratingKeys must be explicit owner-account keys rather than titles or filters. It adds nothing about the numeric string format or the 1-100 item cap, and nothing about the boolean's edge behavior (e.g. marking an already-watched item).

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?

A specific verb pair (mark watched/unwatched) plus the resource (items addressed by ratingKey), with the account scope called out as owner. It is clearly distinct from siblings like watch_history (read) or rate_item, 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?

"Explicit keys only" tells the agent it must already hold ratingKeys (e.g. from search/get_item) rather than addressing items by filter, which is useful implied guidance. However, it never states when to prefer this over rate_item, watch_history, or manage_watchlist, nor any 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 read-only, idempotent, closed-world behavior, so the safety profile is covered. The description's one added behavioral fact is the scope limit ('your own library only'), plus the idea that ordering comes from Plex's own recommendation engine rather than computed similarity; it says nothing about result shape, limit behavior, or failure on an invalid/unknown ratingKey.

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

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

Two tight sentences; the identity of the tool is front-loaded and the filtering note follows only because it adds a non-obvious capability. No filler or restatement of the name.

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

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

For a simple read tool with no output schema, the description covers what the call returns conceptually (a recommendation list) but omits the limit parameter's role and any indication of what an empty result or bad key looks like. Adequate to select the tool, thin on invocation detail.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains watched well (filtering for unseen items) and identifies ratingKey as the item selector, but never mentions limit (default 10, max 50), leaving one of three parameters undocumented anywhere.

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

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

Names a specific verb/resource: Plex's 'more like this' list for one item, addressed by ratingKey. The parenthetical (movie, show, album…) clarifies accepted item types, and 'from your own library only' separates it from a general discovery or search tool among the 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?

The clause 'watched filters the results so similar but unseen is one call' implies a concrete usage scenario, which is real guidance. But it never states when to prefer this over siblings like get_extras, get_children, or search, nor any prerequisites (e.g. whether the item must be in the library).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds non-obvious behavior: default sort is newest first, kind is applied client-side to the returned page, and total is the unfiltered count. Those two quirks are genuinely important because they make filtered results look inconsistent with totals; only permission/auth context is absent.

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

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

Four tight sentences, each carrying distinct information: scope first, then filters, then sort order, then the two counting/filtering caveats. No restatement of the tool name 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?

For an 8-parameter tool with no output schema and thin schema descriptions, the definition covers scope, filtering semantics, sort order, and result-count behavior well. The remaining gap is how limit/offset interact with the client-side kind filter and how to page through the unfiltered set.

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 schema description coverage at 13%, the description carries most of the load and does: user accepts a name or account id, since/until are ISO dates, ratingKey means 'has X seen Y', kind is one of movie/episode/track. limit and offset are left unexplained, though their schema defaults, bounds, and names make their meaning mostly inferable.

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 ("Watch/listen history") with explicit scope ("across ALL users") and an answer shape ("who played what, when"). The all-users framing implicitly separates it from per-user/session siblings like continue_watching and now_playing, and the "has X seen Y?" framing pins down the question it answers.

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 contexts (filter by user, library, time window, or specific item) and a named use case — answering 'has X seen Y?' via ratingKey. It stops short of naming alternative tools or exclusions (e.g., when to prefer continue_watching instead), so it's clear context rather than full routing guidance.

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