TRMNL

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the non-obvious cross-tool linkage of installation_id to fleet and room-booking operations, which is useful, but says nothing about return format, pagination, or 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?

A single front-loaded summary sentence states the resource and scope, followed by a tight bulleted list pairing each action with its effect and parameters. Every line earns its place and the structure makes scanning for the right action trivial.

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 multi-action tool with annotations covering safety and no output schema, the description covers all four operations and their key parameter, plus the installation_id linkage. It stops short of describing what each list/get returns, which is the main 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?

Schema coverage is reported at 100%, but the params object is a generic untyped bag, so the description carries real weight by naming installation_id as the path parameter for both getFleet and listFleetDevices and by omitting it for the two list actions. This adds meaning beyond the schema's bare 'path, query and body parameters by name'.

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

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

The description states a clear resource (account apps and fleets) and enumerates each of the four operations with a specific verb+object: listApps, listAppInstallations, getFleet, listFleetDevices. An agent can tell exactly what each action does. It does not explicitly contrast with the AccountAppsWriteTool sibling, but the read/write split is apparent from the name and readOnlyHint.

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 implies usage by mapping each action to its effect, but it gives no explicit when-to-use or when-not guidance versus the Write sibling or other read tools. The one genuinely useful routing hint is that 'an installation's id is the installation_id the fleet and room booking operations take', which cross-links tools but is not a usage rule.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotent, so the safety profile is covered. The description adds genuine behavioral context: which operations target a fleet's master vs. mirrors, that pushFleet broadcasts the master playlist to every mirror, and which parameters are path vs. body. It stops short of mentioning auth requirements or failure modes.

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 guiding sentence is front-loaded ahead of the per-action list, and each bullet is a tight verb + resource + params line with no filler. The list is long, but that length is dictated by the ten distinct operations the schema exposes.

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 the compound action/params schema would be unusable without the per-action parameter map the description supplies, which it does well. Gaps remain on return content, error behavior, and required-vs-optional nuance, but the essentials for invoking each action correctly 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?

The input schema's 'params' object is an opaque bag documented only as 'path, query and body parameters by name', so the schema alone is insufficient. The description compensates fully by documenting, per action, exactly which parameters are required and whether each is a path or body value (e.g., overdue_alert_threshold_minutes constrained to 30/60/240).

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 states the verbs and resource (install/uninstall an app, manage fleet master/mirrors/settings/alerts/pushes), and the bullet list enumerates every action with its own verb+resource pairing. An agent can distinguish this write tool from AccountAppsReadTool purely from the mutating operations listed.

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 tells the agent which action to pick via the bullet list, and flags that uninstallApp is destructive, but it never states when to use this tool versus AccountAppsReadTool or AccountAuthoringWriteTool, nor any prerequisites. Usage is implied by the action semantics rather than explicitly guided.

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 without description help. The description adds scope of retrievable data (installs, health, failing installs, uninstall feedback) but says nothing about auth requirements, rate limits, or result shape, and there is no output schema to fall back on.

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 scope sentence is front-loaded and the bullets are scannable and appropriately short. There is mild redundancy between 'the third-party plugins it is building' in the lead and the listMyPlugins bullet, but 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 an operation-dispatching tool with a nested, fully opaque params object and no output schema, the description covers action selection but not per-action input requirements or return content. An agent knows which action to pick but not what to pass for getAuthorAnalytics or listAuthorPluginErrors.

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 baseline is 3. The bullets usefully expand opaque enum values such as getAuthorAnalytics and listAuthorPluginErrors beyond their literal names, but the description never states which parameters each operation requires (e.g., a plugin identifier) — the nested params object is documented only as a generic 'path, query and body parameters by name'.

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 lead sentence names the resource (third-party plugins the account authors) and the four read actions, each with a specific verb and object (list, read analytics, list failing installs, read uninstall feedback). This is well past a tautology, but it never names the sibling it is the read half of (AccountAuthoringWriteTool) or contrasts with AccountPluginsTool, leaving differentiation to the tool name.

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 four bullets function as an explicit routing table for choosing among the enum values, which the bare schema enum cannot convey. However, it gives no guidance on when to prefer this tool over AccountAuthoringWriteTool or AccountPluginsTool, and no prerequisites 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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the mutation profile is covered. The description adds useful operational detail — refresh_every allowed values, the 35-character description cap, the path vs body vs query placement, and the shape-matching semantics of hideAuthorPluginError's message — but says nothing about reversibility, permission requirements, or side effects of hiding an error row.

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 overall purpose in one sentence, then organizes the four operations as a scannable bullet list. It is long, but the length is driven by four distinct operations with large parameter sets, so little is wasted; a future editor could trim repeated parameter descriptions shared between create and update.

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-action, nested-parameter tool with no output schema and only wrapper-level schema docs, the description covers all four operations and their inputs. It omits return-value behavior and error/destructiveness consequences, but the annotations carry the safety dimension, leaving only minor gaps.

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?

Top-level schema coverage is 100% but only for the generic 'action' and 'params' wrapper; the real payload is a nested object the schema does not document. The description compensates by enumerating every nested parameter per action, including location (body/path/query), allowed enum values, and semantic notes such as installation_url being the OAuth authorize page. This is genuinely additive over the schema.

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

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

The description uses specific verbs (create, update, hide, unhide) on a specific resource (third-party authored plugins and their error rows), and enumerates the four sub-operations with their parameter sets. It is clearly the write counterpart to AccountAuthoringReadTool in the sibling list, though it never states that relationship explicitly.

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

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

The action list implies when each operation applies, but there is no explicit guidance on choosing between createMyPlugin vs updateMyPlugin (e.g. update requires an existing id), nor routing advice versus AccountPluginsTool or AccountPluginSettingsWriteTool. Usage is inferable from the action names rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real semantic context beyond that: getDeviceForecast 'simulates' check-ins deciding each the way a real one would (i.e., it is a simulation, not real check-ins), and playlist coverage is 'times of the week a playlist shows nothing scheduled'. No auth, rate-limit, or pagination notes are given.

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

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

One front-loaded summary sentence followed by a scannable per-action list; every line carries distinct information and nothing is restated. Appropriate length for a six-operation multiplexed 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?

All six actions, their purposes, and their parameters are covered, which is the main gap such tools have; no output schema exists so return-value detail is not required. Minor omissions remain around pagination/limits (e.g., limit semantics) and when to prefer one action over another.

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 top-level schema only exposes an opaque 'action' enum plus a generic 'params' object, so the description's mapping of each action to its named path/query parameters (id, device_id, level, source, limit, before_ts, before_event_id, hours, date) supplies meaning the schema does not. It does not explain parameter formats, defaults, or valid ranges.

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

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

The opening sentence names the specific resource (the account's devices) and enumerates the six concrete operations, so an agent knows exactly what the tool can do. It does not explicitly distinguish itself from AccountDevicesWriteTool, which is left to the Read/Write naming convention rather than stated in the text.

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

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

The per-action breakdown effectively routes the agent to the right sub-operation (list vs. single device vs. logs vs. forecast vs. coverage vs. timeline). There are no exclusions or explicit comparisons against sibling read tools, so it stops short of full when/when-not 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 declare destructiveHint=true for the whole tool, and the description adds genuinely useful nuance by narrowing that to specific actions ('clearDevicePlaylist is destructive') and clarifying that stopMirroringDevice removes only the mirror link, not data. That prevents an agent from treating every action as data-destroying. It still omits auth/permission requirements, reversibility of clearDevicePlaylist, and any rate-limit or failure 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 purpose sentence is front-loaded, followed by a scannable per-action bullet list matching the enum order, and the destructive caveats are surfaced immediately after the intro. It is long, but the length is justified by eight actions and ~35 nested parameters; a few body descriptions (e.g. sleep_until) are wordy though each detail 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?

With no output schema, the description needn't cover return values, and it does cover all eight actions plus their parameters and the key destructive semantics. Gaps are secondary: no mention of required permissions/scope, no error or partial-failure behavior, and no confirmation that unlisted device fields are left untouched by updateDevice.

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

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

The schema only exposes a generic 'params' object with no per-action structure, so the description carries the full burden and does so: every action's path/body params are listed by name with units, ranges (300-86400 seconds, 0-1439 minutes), enums (visibility, firmware_channel, touchbar_mode, text_scale, playlist_item_ttl, framework_size), and behavioral notes (sleep_until ISO 8601 semantics, auto_advance beta caveat tied to management.writable_fields). This is meaning far beyond anything the structured 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 opening sentence states a concrete verb+resource scope ('Claim an unclaimed device, change a device's settings, flash its screen...') and the body enumerates all eight write actions with the exact operation names used in the enum. It clearly distinguishes itself from the sibling read tool AccountDevicesReadTool by being the mutation counterpart.

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 annotated with its intent (claim vs update vs mirror vs resync vs retry), and the description explicitly warns that clearDevicePlaylist is destructive and that stopMirroringDevice is a DELETE that only clears the mirror link. It cross-references helper lookups (listModels, listPalettes) for enum values. It stops short of stating when to prefer this tool over AccountDevicesReadTool or excluding misuse cases.

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 structurally. The description adds a genuine workflow dependency — that preview/refresh results only exist after another tool has started a job — which is context the annotations cannot convey. It stops short of describing readiness/error states or rate limits.

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

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

The opening summary sentence is a fragment ('A private plugin's markup by size, and...'), which is slightly awkward, but the per-action bullets are densely structured and front-load the operation name followed by its parameters. Every line carries information; there is 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?

There is no output schema, yet the description says only that getPreview/getRefresh return 'the result' without indicating the return shape (markup content, image URL, render status). For a three-operation read tool this leaves the agent knowing how to call it but not what to expect back, or how a pending/failed job manifests.

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

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

The schema only defines a generic 'params' object with no per-property documentation, so the description carries the parameter burden and does so well: it names plugin_setting_id, size and id per operation, flags them as path parameters, and enumerates the size enum values (markup_full, markup_half_horizontal, ...) that appear nowhere 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?

The description names the resource (private plugin markup) and enumerates the three operations it exposes, with the scope of each sub-action stated. It implicitly points at its write counterpart ('the Change markup tool') rather than naming the sibling AccountMarkupWriteTool, so differentiation is clear in substance but not exact in naming.

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 tells the agent that getPreview/getRefresh are for retrieving results of jobs 'started with the Change markup tool', which gives real sequencing guidance rather than mere implied usage. What is missing is any exclusion or fallback guidance (e.g., what to do if the job has not finished, or when to prefer readMarkup over a preview).

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the risk profile is covered. The description adds useful async behavior (job-id polling vs fire-and-forget queueing), but never states that writeMarkup overwrites existing markup for that size, nor any auth or side-effect details beyond the annotations.

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 polling rule, then clean per-action bullets with params inline. The opening sentence is dense and mixes the three actions with the polling caveat, which slightly hurts scanability, 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?

For a multi-action dispatcher with nested params and no output schema, the description covers the key unknowns: per-action arguments and the async return/polling contract. Missing only overwrite semantics for writeMarkup and any per-action error or permission notes.

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

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

The schema only exposes generic 'action' and 'params' objects, so the description carries most of the semantic load by enumerating each action's path/body arguments, including the full size enum and the optional device_model. Coverage is effectively complete, but field-level typing and required-vs-optional status are still partly implicit.

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 three concrete operations (writeMarkup, startPreview, startRefresh) and states what each does with its resource (plugin markup / plugin instance), so an agent knows exactly what will happen. It does not explicitly contrast with the sibling AccountMarkupReadTool, though it references getPreview/getRefresh as the read counterparts.

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 a real decision rule: startPreview and startRefresh on a polling instance return a job id to poll, while any other refresh queues a render and yields nothing to poll. That is actionable routing guidance. It stops short of saying when to prefer writeMarkup versus other authoring 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, and the description does nothing beyond that safety profile — no pagination behavior, auth requirements, permissions, or scoping limits. It does not contradict the annotations, but it adds no behavioral context the structured fields don't already 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-loaded one-line scope statement followed by one bullet per action with params inline; very little waste. The opening sentence is slightly overloaded ('and the mashups that split one screen between plugin settings') but overall tightly structured.

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 five-operation dispatcher with a free-form params object and no output schema, the description covers operation selection and parameter names but says nothing about return shapes, pagination, or error behavior. Adequate for invocation, incomplete about results.

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

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

The schema's `params` object is untyped free-form, so the description's per-action parameter listing (device_id, item_id, id, mashup_id plus date, with path/query locations) supplies semantics the schema does not. It omits types and the expected date format, 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?

The description states a concrete resource and scope ('Device playlists: what each device shows, in what order and on what schedule, and the mashups...') and enumerates the five read operations, so an agent can distinguish it from AccountPlaylistsWriteTool and the plugin-settings tools. It stops short of naming the write sibling explicitly, so the read/write split must be inferred from 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?

The per-action bullets imply which action to pick for a given need (device playlist vs. playlist items vs. schedule vs. mashup vs. timeline), which is real routing help for a dispatcher. However there is no explicit when-to-use/when-not-to-use guidance and no mention of the write counterpart, so usage is only implied.

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

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

Annotations already declare destructiveHint=true, but the description usefully refines this by localizing destruction to deletePlaylistItem rather than implying every action is destructive. It still omits auth requirements, reversibility, and per-action idempotency behavior, which matters given 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?

The summary sentence is front-loaded and the per-action bullets are tightly scoped to routing and parameters, each earning its place. It is long, but the length is justified by 11 distinct actions with no wasted prose.

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 write dispatcher with no output schema, the description covers every action and its parameters completely enough to invoke correctly. It could add return-value expectations and permission requirements, but nothing essential for invocation is missing.

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

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

The schema only exposes a generic {action, params} wrapper, so the description carries nearly all parameter meaning. It documents each action's path/body params, enumerates value sets (layout 1x1..3x3, action_type hide/show), and specifies formats (week_days 0=Sunday, HH:MM 00:00-23:59, contents by position) — far 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?

Opens with a specific verb+resource ('Change device playlists') and enumerates the full action scope (add, reorder, copy, update, duplicate, delete, schedules, mashups). Combined with the sibling AccountPlaylistsReadTool name, an agent can immediately distinguish this write dispatcher from the read tool.

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 bulleted action list gives context for selecting the correct sub-action, which is useful routing guidance. However, it never states when to use this tool versus AccountPlaylistsReadTool, nor any exclusions or prerequisites; usage is only implied.

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 behavior, so the safety profile is covered. The description adds one genuine behavioral nuance — getPluginSettingData serves native plugins while private plugins must use getMergeVariables — but says nothing about authorization scope, pagination, or result shape.

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 leading sentence frames the tool before a tightly formatted bullet list, one line per action, with zero filler. The opening phrase 'list and inspect them' is slightly redundant with the listPluginSettings bullet, a minor blemish rather than bloat.

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

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

For a seven-action dispatcher with no output schema and a generic params container, the description covers every action and its inputs, which is the critical information. It leaves auth requirements and response shape unstated, but the absence of an output schema lowers that burden.

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 outer schema only defines a generic 'params' object, so the description meaningfully compensates by naming each action's actual parameters (plugin_id, id, plugin_setting_id, level, limit, date) and marking each as path or query. It omits types, required flags, and default values, so it is not fully self-sufficient.

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 opens with a specific verb and resource ('list and inspect the account's plugin instances') and enumerates seven concrete read operations, so an agent knows exactly what the tool surfaces. It does not explicitly differentiate itself from AccountPluginSettingsWriteTool or AccountPluginsTool beyond the implied 'Read' naming, 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?

Each sub-action is paired with a one-line statement of what it retrieves, which effectively routes the agent to the right action ('a private plugin reads through getMergeVariables', 'Read plugin instance health and recent logs'). There are no explicit exclusions or a stated rule for choosing between this tool and its write/plugin siblings, keeping it out of the top band.

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 carry readOnlyHint=false, destructiveHint=true and idempotentHint=false, but the description adds real value by narrowing destructiveness to deletePluginSetting and resetPluginSettingCredentials rather than the blanket hint, and by explaining side effects such as 'Forget the linked account and remove the plugin setting' and 'Turn on debug logs for a day'. It does not cover return behavior, but the safety picture is materially enriched beyond the annotations.

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?

Sized appropriately for a 16-action dispatcher with no wasted prose; the general purpose leads and the per-action bullets are terse and scannable. The list is necessarily long, but each line earns its place by disambiguating an enum value and its params.

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?

Given no output schema, a destructive multi-action dispatcher, and nested params, the description supplies enough to select and call any action correctly. It omits mention of permissions/auth requirements and response shapes, which is a minor gap rather than a blocking one.

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?

Top-level schema description coverage is 100% but the schema only models generic action/params, so the description does the heavy lifting by specifying each action's path/query/body parameters, including the refresh_interval enum values and the base64 image format. This adds meaning well beyond the structured schema and genuinely helps correct invocation.

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

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

The opening sentence names a specific verb set (create, rename, configure, copy, delete) and resource (plugin instances / plugin settings), and the name/sibling set makes clear this is the write counterpart to AccountPluginSettingsReadTool. Each of the 16 sub-actions is enumerated with its verb and resource, so an agent can identify the exact operation 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?

The per-action descriptions act as strong selection guidance among the 16 enum values (e.g., copyPluginSetting vs importPluginSettingFiles vs uploadPluginSettingImage), and it flags the two destructive operations. It stops short of stating when to prefer this tool over the Read sibling or the broader AccountPluginsTool, so context is clear but no explicit 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without description help. The description adds that getPlugin returns form fields, but says nothing about pagination behavior for listPlugins despite cursor/page_size params, so extra context is modest.

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 front-loaded one-line summary followed by a compact per-action bullet list with param names. Every sentence carries information and the structure is easy to scan, though the opening clause is slightly awkward.

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 catalog tool with no output schema, annotations covering the safety profile, and full schema coverage, the description supplies the per-action param mapping and the list-then-read workflow. It is largely complete; only pagination/return-shape details for the list action are absent.

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%, but the schema only exposes a generic 'params' object; the description adds real value by mapping specific parameter names (category, query, page_size, cursor for listPlugins; id for getPlugin) to each action. This disambiguates which params belong to which operation, going beyond what the nested schema conveys.

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 concrete verbs and resources ('list plugins available to install', 'read a plugin and its form fields') and frames the scope as plugins you can create a plugin setting for, which loosely ties it to the AccountPluginSettings siblings. It is clear what the tool does, though it does not name a sibling tool directly.

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?

'search or list them, then read one's form fields' implies a two-step workflow (list first, then getPlugin by id), which is useful implied usage guidance. However there is no explicit when-not condition, no mention of alternatives like AccountPluginSettingsReadTool, and no preconditions stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description usefully adds the 'signed-in account' scoping, but says nothing about what each action returns, pagination, or any auth/permission requirements. Adequate but not rich given the lower bar annotations set.

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 scoping sentence is front-loaded and the four bullets are terse and scannable. The bullets largely mirror the enum entries, so there is minor redundancy, but nothing is wasted or overlong.

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 carry the burden of indicating return content, and the opening sentence covers that at a high level. But it does not describe the shape of results per action or what the nested params object accepts, which leaves gaps for a four-in-one read tool.

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

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

Schema description coverage is 100% and the action enum is fully documented in the schema, so baseline 3 applies. The bullets add a human-readable gloss for each action value ('Get my user data'), which is marginally helpful, but the nested params object is given no explanation in the description.

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 specific resources across four operations: the signed-in account's profile and time zone, plus device models, palettes and plugin categories. An agent can tell what it will get. However it offers no differentiation from siblings like AccountDevicesReadTool, which overlaps squarely with the listModels action.

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 bullets restate the enum values with a short gloss but never say when to use an action, what prerequisites exist, or how this differs from AccountDevicesReadTool/AccountThemesReadTool/AccountPluginSettingsReadTool. No when/when-not guidance of any kind is present.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds useful body-parameter detail, but says nothing about whether updates are partial or full replacements, whether omitted fields are cleared, or what happens on failure.

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

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

One sentence of purpose followed by a single compact bullet. The repeated '(body)' qualifier on every field is mildly redundant, but overall it is front-loaded and wastes little 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 single-operation write tool with no output schema and a nested params object, the description covers every field the caller can pass and its expected format. Only the semantics of partial vs. full updates are missing, which is a modest 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?

Top-level schema coverage is 100%, but the nested body parameters are documented only in the description, and it earns its place: 'time_zone (body: An IANA name or Rails zone name)' and 'title_bar_enabled (body: Show the title bar on every screen)' add format and semantics the schema does not carry.

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: 'Change the signed-in account's profile and time zone.' That is unambiguous, and the write-vs-read distinction against the sibling AccountProfileReadTool is implied by the tool name. It stops short of explicitly naming the sibling, 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 never says when to use this versus alternatives, nor any precondition such as needing an authenticated session. The bullet simply enumerates the one operation ('updateMe') available, which is closer to reference material than usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that these are other users' published recipes (a scope constraint) but says nothing about auth needs, pagination behavior, or rate limits beyond what annotations provide.

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

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

One summary sentence followed by a compact per-action bullet list, with the purpose front-loaded. The parenthetical '(query)'/'(path)' tags are slightly redundant noise, keeping it out of the top band, but overall it earns its 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?

There is no output schema, so the description carries some burden for describing returns; it gestures at them ('how it installs', 'its markup') but does not characterize response shape for search results or the recipe object. Adequate for routing, thin for interpreting results.

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

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

Schema coverage is 100% and the baseline would be 3, but the top-level schema only exposes a generic 'action' + 'params' object and never lists query/sort_by/limit/page_size/cursor/id/sizes. The description is the sole place mapping parameter sets to each operation, which is meaningful information not carried by the structured data.

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 clause names the resource and its scope precisely: 'Recipes other users published' with three specific read operations (search, read one/how it installs, read markup). This cleanly separates it from the write sibling, but it never names AccountRecipesWriteTool or AccountMarkupReadTool explicitly, so differentiation is inferred rather than stated.

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 three sub-actions are each explained ('search them', 'read one and how it installs', 'read its markup'), which implies when each action applies, but there is no explicit when-to-use-this-vs-alternatives guidance and no mention of the AccountRecipesWriteTool boundary. Usage is implied rather than declared.

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, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds genuine context beyond that — the install joins a device's playlist and inherit_oauth carries the author's OAuth connection — but omits permission requirements, reversibility, and duplicate-install 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 lead sentence is front-loaded and the bullet efficiently maps parameters to their roles. There is minor redundancy in restating 'Install a recipe' inside the bullet and echoing the title, but nothing bloated.

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 non-idempotent write tool with no output schema and nested parameters, the description covers the operation and its parameters adequately. It leaves open the re-install/duplicate outcome implied by idempotentHint=false and says nothing about required scopes or what the response contains.

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 top-level schema documents only 'action' and a generic 'params' object, so the description meaningfully supplements it by naming and explaining the nested fields: id (path), device_id (the device whose playlist the install joins), and inherit_oauth (carries the author's OAuth connection for oauth_choice recipes). That is real semantic value above the 100% top-level coverage 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 names a specific verb and resource ('Install a recipe another user published onto a device') and scopes it to the installRecipe operation, which an agent can distinguish from the sibling AccountRecipesReadTool. It stops short of explicitly naming siblings or stating what makes this different from other write tools in the Account*WriteTool family.

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 phrase 'another user published' implicitly constrains usage to recipes you do not own, and the device_id description implies the install targets a device playlist. However, there is no explicit when-to-use vs alternative guidance, no prerequisites, and no mention of what happens if the recipe is already installed.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only two behavioral facts beyond that: installation_id provenance and that getRoomBookingIntegrationConnectUrl returns a URL meant to be handed to the owner. It says nothing about pagination on the list operations, result shapes, or any auth needed to reach an installation.

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 structured bullet list is well front-loaded and scannable, but the preceding single-sentence inventory of the domain ('its summary, billing state and settings; its calendars and what each device showing one has rendered...') is a hard-to-parse run-on that largely previews the same resources the bullets then enumerate. Trimming or merging that opener would sharpen the definition without losing content.

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

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

For an 11-operation dispatcher with no output schema, the description covers the essential routing information: every action, its parameters, parameter location, and where installation_id originates. It is missing return-value/pagination expectations for the list actions and any note on how failures per action surface, which keeps it from being fully self-sufficient.

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

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

The schema's params object is opaque ('path, query and body parameters by name'), so the description is the only place that enumerates which parameters each action takes and whether they are path or query (e.g. id path, from/to/status query). That is real added meaning, though it stops at names and locations — no formats, types, or valid status values are given, and the per-action mapping only works if the agent reads the bullet for the chosen 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 bulleted action list gives a specific verb+resource for each of the 11 operations (getRoomBooking, listRoomBookings, getRoomBookingBilling, etc.), so the agent can tell what each sub-operation does. The opening sentence is a dense noun-phrase run-on that never states a clear 'read X' verb for the tool as a whole, and the sibling AccountRoomBookingWriteTool is never named as the mutating counterpart.

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 lines effectively route the agent to the right sub-operation (bookings vs calendars vs screens vs integrations), and it explicitly states 'The installation_id comes from listAppInstallations', giving a prerequisite/where-to-get-input instruction. However, there is no explicit when-not-to-use guidance and no direct reference to AccountRoomBookingWriteTool for mutations beyond the naming convention.

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=true, idempotent=false, and readOnly=false, so the safety profile is covered. The description adds real value beyond them: it names what gets removed (logos, calendars, collections, accounts), clarifies timing semantics ('cancel an upcoming booking' vs 'end a booking in progress now', 'refetch now'), and points to listAppInstallations as the source of installation_id.

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 front-loaded summary sentence is followed by a dense but well-structured per-operation list; each line carries required information for the opaque params object. It is long, but the length is driven by 22 operations rather than 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 22-operation write tool with a nested, untyped params object and no output schema, the description covers every action and its parameters, which is what an agent needs to invoke it. It does not describe return values or error behavior, a minor gap given no output schema exists.

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

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

The input schema is effectively opaque — a single 'params' object described only as 'path, query and body parameters by name'. The description compensates fully by documenting every operation's path/body fields, their types, and enum values (time_format, collection_type, display_layout), adding far more than 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 opening sentence states a specific verb and resource ('Change a room booking installation') and enumerates the full scope: settings, logos, calendars, bookings, collections, and connected accounts. It is clearly a mutation tool distinguishable from the read sibling by scope, though it never names AccountRoomBookingReadTool 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 22 enumerated operations rather than stated. There is no explicit when-to-use/when-not guidance, no note about the read counterpart, and only one hint about prerequisites ('installation_id comes from listAppInstallations').

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds that getUserTheme takes a path 'id', which is minor extra context; it says nothing about auth requirements, pagination for listUserThemes, or error 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?

Three short lines, front-loaded with the resource and followed by a compact action list. Nothing is padded, though the bullet formatting is slightly mechanical.

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 tool whose annotations cover the safety profile and whose schema enumerates the actions, the description supplies the key missing piece (the id param for getUserTheme). No output schema exists, but list/get return shapes are self-evident; only pagination behavior for the list action is unaddressed.

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 reported at 100%, so the baseline is 3. The description does add one useful detail the schema does not carry — that getUserTheme requires an 'id' path parameter — but leaves the shape of the generic 'params' object otherwise unexplained.

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 ('the user's saved framework themes') and both read operations (listUserThemes, getUserTheme), so the agent knows exactly what this tool returns. It does not explicitly contrast with the sibling AccountThemesWriteTool, but the read-only framing and tool name make the split clear.

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 enumerates the two actions with one-line glosses ('List my themes', 'Read a theme'), which implies list-for-many / get-for-one usage. There is no explicit when-to-use guidance, no statement of prerequisites, and no mention of the write sibling as the alternative for 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 already declare destructiveHint=true for the whole tool, so the description's explicit 'deleteUserTheme is destructive' adds per-action granularity — it clarifies that only the delete action is destructive rather than the entire write surface, which prevents over-caution on create/update. It does not cover auth requirements or reversibility beyond that.

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

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

One framing sentence followed by a tight per-action bullet list; the destructive caveat is front-loaded in the first line. 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?

Covers all four operations and their required arguments, which is the bulk of what an agent needs for a tool with no output schema. It stops short of describing response shape or what a successful update/delete returns, a minor gap given the schema's generic params container.

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

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

The schema only documents a generic action enum and an opaque 'params' object, so the description carries the real payload semantics: it maps each action to its path/body params and clarifies formats the schema omits, e.g. 'name: Unique per account' and the token being usable 'with or without the URL around it'.

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

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

The opening sentence names a specific verb set (create/update/delete/import) against a specific resource (user's saved framework themes, plus shared snippet import). It also enumerates each concrete operation, so an agent can distinguish this write tool from the sibling AccountThemesReadTool 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?

Each action is spelled out with the parameters it needs, which tells the agent which operation to select for a given intent. It does not, however, state when to prefer this tool over AccountThemesReadTool or give prerequisites/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 readOnly, idempotent, non-destructive and openWorldHint=false, so the safety profile is covered. The description adds useful domain semantics (the catalog is third-party and free, suitable for plugin polling) but says nothing about result volume, pagination, or rate limits beyond what the schema states.

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

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

Two tight sentences, front-loaded with the resource and immediately followed by the disambiguating negation. The final clause ('Returns endpoints matching your query, filterable by category') largely repeats the schema but does not bloat the 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?

There is no output schema, but the description states what comes back (matching endpoints) and the schema covers all three parameters. Combined with annotations that carry the safety profile, an agent has enough to call this correctly; only return-shape detail is thin.

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 query, category and limit are fully documented in the schema. The description only restates query matching and category filtering, adding no format or syntax detail beyond the baseline expectation.

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

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

States a specific verb (Search) and resource (catalog of free third-party APIs) plus the consumer context (a private plugin polling for data). The explicit exclusion 'Not TRMNL's own API' distinguishes it cleanly from the Account* sibling tools, which all manage TRMNL account 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?

Gives clear context for when to reach for it: finding third-party endpoints a plugin can poll, with a negative exclusion for TRMNL's own API. It stops short of naming a specific alternative tool or stating preconditions, but the boundary against siblings is unambiguous.

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