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

Goes beyond annotations by disclosing that credentials are host-injected and that passwords must never be passed as arguments — non-obvious, security-relevant behavior. Annotations already flag non-read-only/open-world/non-destructive, so the remaining gap (session lifetime, failure behavior) is minor rather than disqualifying.

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 the action and the prerequisite, and the security constraint placed last where it reads as a warning. No wasted words.

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?

Annotations cover the safety profile and there is no output schema to explain, but the definition omits the only input (profileId), where profiles come from, and what a successful call establishes for subsequent tools. Adequate for a login tool, yet with a clear gap around the sole 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 coverage is 0% and the single parameter profileId is never mentioned, so an agent gets no explanation of what a profile is, how to obtain an ID, or that it is the only required input. With no param documentation anywhere, the description fails to compensate for the coverage 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?

States a specific verb (log in) and resource (server) and clarifies the credential source, which distinguishes it from the surrounding import/upload/discover siblings. It stops short of saying what authentication yields or how it relates to other server tools, but the action itself 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 clause 'does not require a prior browser login' is a genuine prerequisite statement that tells an agent this call is self-sufficient. It does not name alternatives or exclusions (e.g., when discover_server vs this tool applies), but the context it supplies is clear rather than merely 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 readOnlyHint, openWorldHint, and destructiveHint=false. The description adds the useful assurance 'No credentials are sent', which is meaningful beyond the annotations, but it does not describe probing behavior, timeout/error handling, or what discovery returns.

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

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

Two short sentences with no wasted words, and the primary purpose is stated first. The structure is front-loaded and easy to scan.

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 open-world discovery tool with no output schema and 0% schema description coverage, the description does too little. It communicates the core action and credential safety, but not what discovery returns, how ports are used, or what happens when no server is found.

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 clarifies that 'host' refers to a single user-specified host, but it says nothing about the optional 'ports' parameter, leaving that parameter undocumented in both schema and 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 states a specific verb and resource: 'Discover Jellyfin on one user-specified host.' This is clear enough to separate it from authenticate_server and other siblings, but it does not explicitly differentiate itself or name alternatives.

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 'on one user-specified host' implies the tool should be used when a host is known and the goal is discovery, but it does not state when to use it versus alternatives such as authenticate_server or inspect_connection, nor does it mention 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description's valuable addition is 'non-secret', which tells the agent no credentials are exposed. However, it doesn't clarify whether 'export' returns data in the response or produces an artifact, nor whether authentication is required.

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 tight sentence with the positive purpose front-loaded and the negative scope trailing. Every clause carries information; nothing is redundant.

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-only tool with annotations covering safety, this is close to sufficient, but the unspecified profileId and the unresolved question of what the export actually produces leave a meaningful gap for correct invocation.

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 profileId has 0% schema description coverage and the description says nothing about what a profile ID is or where to obtain one. With only one parameter the burden is small, but the description adds no meaning beyond the schema's string constraint.

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 (Export) and resource (non-secret connection information) plus the intent (future client pairing). It is distinguishable from the sibling inspect_connection, but it never names the sibling, leaving the export-vs-inspect distinction to be inferred.

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

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

Gives a clear positive context ('for future client pairing') and an explicit exclusion ('does not configure the Apple app'), which steers the agent away from a plausible misuse. It stops short of naming an alternative tool for the excluded case.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description's one contribution is that output covers both implemented and unavailable features, which tells an agent that missing entries are meaningful rather than errors. It adds nothing about what a capability record contains or how it is scoped.

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

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

It is a single short sentence with no filler, so nothing is wasted. But the brevity is under-specification rather than discipline: the one sentence is spent on a near-restatement instead of on scope or usage.

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 parameters and no output schema, the description is the only place an agent can learn what a 'capability' is here and what the report looks like. It supplies neither, leaving the agent to guess at scope and result shape before calling an open-world inspection 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?

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description does not need to compensate for anything here.

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 largely restates the tool name: 'inspect_capabilities' becomes 'Report implemented and unavailable features.' It never states whose capabilities are being inspected (the server itself, a connection, a plugin), which matters because siblings include inspect_connection, inspect_server, inspect_tailscale, and inspect_import_metadata.

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 when-to-use guidance, no prerequisites, and no mention of any sibling as an alternative. An agent cannot tell from this text whether to call it before authenticate_server, after discover_server, or instead of inspect_connection.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope by noting verification of public server identity including a reverse-proxy base path, but it does not describe authentication needs, network failure behavior, or what verification actually returns.

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

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

The description is a single front-loaded sentence with no filler. It leads with the verb and resource, then adds the relevant URL scope.

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

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

For a simple one-parameter read-only inspection tool, the description covers purpose and URL scope, and annotations cover safety. However, with no output schema, the description leaves unclear what "verify" returns and how failures or unreachable servers are reported.

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 for the single url parameter. It does add meaning by saying the URL should be a full URL including any reverse-proxy base path, which goes beyond format=uri. However, it does not specify scheme expectations, trailing-slash behavior, or how the base path should be represented.

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

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

The description states a specific verb and resource: "Verify public server identity" at a full URL, including a reverse-proxy base path. It is clear what the tool does, but it does not distinguish itself from siblings such as discover_server, authenticate_server, or inspect_capabilities.

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 the tool is for verifying public server identity at a full URL, but it gives no explicit when-to-use guidance, no exclusions, and no alternatives such as discover_server or authenticate_server. An agent must infer when this is the right choice.

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

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

Beyond the readOnly/non-destructive/openWorld annotations, the description adds real value: it explains that external changes are captured as a new baseline revision 'without changing media,' and states a hard prerequisite ('Requires the metadata-capable native plugin'). This is meaningful behavioral context the annotations do not 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?

Three compact sentences with the core purpose front-loaded, then behavior, then prerequisite. Little waste, though the baseline-revision sentence is dense and could be clearer.

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?

It nicely implies the return value ('use the returned revision') and covers the plugin prerequisite, which suits a read-only inspect with no output schema. The remaining gap is parameter documentation for the two required identifiers, which the description does not fill.

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% and both profileId and jobId are opaque identifiers. The description's 'your own completed video import' loosely implies jobId identifies the import, but neither parameter's meaning, format (the UUID pattern), or relationship is explained, leaving the agent to infer from the schema alone.

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 ('Inspect') and resource ('fields, artwork, revision history and durable verification state of your own completed video import'), which is concrete and distinguishable from siblings like update_import_metadata. It scopes to a 'completed' import but does not explicitly contrast itself with the sibling mutation 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 phrase 'use the returned revision for later edits' implies this is the read step preceding edits, hinting at update_import_metadata as the follow-on. However, no alternatives are named explicitly and there is no clear when-not-to-use guidance, 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the useful boundary that it does not configure the VPN, but it does not elaborate on output shape, network behavior, or permissions 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?

The definition is a single efficient sentence. The positive scope is front-loaded and the exclusions follow immediately, with no 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 zero-parameter, read-only inspection tool with no output schema, the description supplies enough to understand what is returned conceptually (peer names and addresses) and what it does not do. It could say more about whether results are local-only or network-wide, but the core is adequate.

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?

There are zero parameters, so there is no parameter semantics burden. The description correctly adds no misleading parameter detail, matching the empty 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 a specific verb ("Inspect") with a clearly scoped resource ("local Tailscale peer names and addresses"). It is materially clearer than a tautology, though "inspect" remains somewhat broad and no sibling tool covers the same resource for direct contrast.

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 explicit exclusions: it does not configure VPN or prove Jellyfin identity. This helps an agent avoid misusing it for configuration or identity verification, even though no positive alternative tool is named.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that it reuses the existing restricted login rather than performing new authentication, which is useful behavioural context, but says nothing about failure modes, cost, or what a 'check' result means.

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 economical sentence with the resource front-loaded. It is underspecified rather than bloated, so length itself is not the problem.

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

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

For a tool with an undocumented required parameter, no output schema and an ambiguous outcome ('check' returning what?), the description leaves too much unknown for an agent to call it confidently or interpret the result.

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?

There is one required parameter (profileId) with 0% schema description coverage, and the description does not mention it at all — no indication of what a profile ID refers to or how to obtain one. With low coverage the description needed to compensate and does not.

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 resource (the native WatermelonFin Jellyfin plugin) but the verb 'Check' is vague — it does not say whether it verifies installation, version, configuration or health. It also fails to differentiate itself from sibling inspect_* tools (inspect_connection, inspect_capabilities, inspect_tailscale).

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?

'using the existing restricted Jellyfin login' implies a precondition (a restricted login must already exist), which is genuine usage context. However, there is no statement of when to prefer this over inspect_connection or list_upload_targets, and no 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description contributes the useful extra detail that results are scoped to a low-privilege view, implying the output may be a subset of what an admin would see. It says nothing about pagination, result size, or what happens if profileId is invalid, so it adds only modest value beyond 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?

A single front-loaded sentence with no filler. The only inefficiency is the vague 'dedicated user' clause, which spends words without resolving the ambiguity it creates.

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 with no output schema and solid annotations, the description is close to sufficient, but the completely undocumented profileId leaves a real gap for an agent that must supply it correctly. One clause about the identifier would make this complete.

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

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

There is one required parameter, profileId, with 0% schema description coverage, and the description never mentions it. The agent gets no help on whether profileId is a server profile, a user profile, or an identifier format. With schema coverage this low, the description needed to compensate and does not.

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 ('List') and resource ('libraries') and adds a scope qualifier about the permission level of the viewing user. The phrase 'dedicated user with no administrative or deletion permissions' is unusual phrasing but still signals that this returns a restricted view rather than everything on the server. It is distinct enough from siblings like list_upload_targets or search_media that an agent can pick it 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The permission qualifier hints at the audience but doesn't tell an agent which sibling to choose when it needs library data versus media or upload targets.

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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds a useful behavioral constraint by stating that arbitrary filesystem browsing is never exposed, but it does not cover authentication, profile scoping, or result 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 definition is a single front-loaded sentence with no filler, and the security constraint is placed immediately after the core purpose. It is concise and efficient, though the phrase "native plugin import targets" is somewhat dense.

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-only list tool, the description is still under-specified: it does not explain the required profileId or how the returned targets relate to the nearby upload and import tools. Annotations and the schema provide some structure, but the description leaves important invocation context implicit.

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 has one required parameter, profileId, with 0% schema description coverage, and the description does not explain what profileId means or how it scopes the listed targets. The description therefore does not compensate for the missing parameter documentation.

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 has a clear verb ("List") and resource ("configured native plugin import targets"), and it clarifies that it does not expose arbitrary filesystem browsing. It does not explicitly distinguish itself from sibling tools such as inspect_upload_plugin, upload_media, or list_libraries.

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 offers no explicit guidance on when to use this tool versus alternatives. The phrase "never exposes arbitrary filesystem browsing" sets a safety boundary but does not tell an agent when this listing should be selected over inspect_upload_plugin or upload_media.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the 'does not touch existing media' line largely restates the safety profile rather than adding new behavior. The description does not disclose what a 'proposal' consists of, whether it is persisted, or what the follow-up call would be, which is the missing behavioral context here.

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

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

Two short sentences with zero filler, and the key constraint (planning only, non-destructive) is front-loaded. Nothing could be removed 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?

There is no output schema, so the description is the only place an agent could learn what a 'proposal' returns (e.g., target library, path, metadata fields) and how to act on it. Given the import pipeline implied by the sibling tools, this return-value context is a real gap, though the mutation-safety aspect is fully covered.

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 single fileName parameter relies entirely on the description, which at least clarifies it is a 'newly selected filename' rather than an existing path. It does not state whether a full path or bare name is expected, nor the 1-180 length constraint's practical meaning. With only one simple parameter this is adequate but thin.

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: 'Propose organization' for 'a newly selected filename.' The scope qualifier 'only' and the note about existing media make the intent distinguishable as a planning/dry-run step. It stops short of naming a sibling or saying what kind of 'organization' is proposed (library, path, metadata), so it is not 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 a newly selected filename only' and 'Does not touch existing media' imply this is used before an import, not for existing items, which is useful implicit guidance. However, it never explicitly says when to call it versus upload_media, update_import_metadata, or inspect_import_metadata, nor whether it precedes or follows an upload.

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 and openWorldHint=true, so the write-plus-external-server profile is known. The description adds genuinely new context beyond that: the mutation is scoped to 'only its indexed Jellyfin item' (blast-radius limit) and that it reports pending/mismatched state rather than forcing convergence. It still omits idempotency, failure modes, and whether a mismatched/conflicting revision aborts the call.

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, front-loaded with the action, no filler. Density of domain jargon ('owned-import metadata revision', 'indexed Jellyfin item') costs some readability but every clause carries 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?

This is an open-world mutation with three undocumented required parameters and no output schema, which raises the description's burden. It partially compensates by describing the scoped target and that the result reports pending/mismatched state, but leaves the shape of that report and the semantics of the revision token unexplained, so an agent cannot reliably construct a correct call.

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 all three required parameters, so the description must carry the burden and largely does not. 'Current ... revision' vaguely hints that expectedRevision is a concurrency/optimistic-lock token, but jobId vs profileId are never explained, nor is the meaning of the 'initial' sentinel in the expectedRevision pattern.

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 (reapply/refresh) paired with a specific resource (the current owned-import metadata revision and its indexed Jellyfin item), so the action is identifiable. However, it never names or contrasts with the closest siblings — update_import_metadata, restore_import_metadata, inspect_import_metadata — leaving the agent to infer the boundary between 'reapply current revision' and 'update' or 'restore'.

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: 'reapply the current' and 'reports pending or mismatched state' suggest it is for repairing drift rather than making changes, but the description never states when to pick this over update_import_metadata or restore_import_metadata, nor any preconditions (e.g. that the revision must already be owned/applied).

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, and openWorldHint=true. The description adds useful behavioral context beyond annotations: it creates a new revision rather than overwriting, and it never changes video bytes. However, it does not disclose permission requirements, concurrency behavior (expectedRevision), or what happens to the current metadata revision.

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

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

Two sentences with zero waste, front-loading the core action and following with the critical safety constraint. Every phrase 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?

For a four-parameter mutation with no schema descriptions and no output schema, the description is too sparse. It omits parameter explanations, concurrency semantics, and the effect on existing revisions, leaving the agent under-informed despite the useful 'never changes video bytes' note.

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 of explaining all four required parameters. It only vaguely references a 'journaled revision' and 'your own completed upload' without mapping jobId, revision, or expectedRevision to their purposes or formats. This leaves significant gaps for 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?

States a specific verb ('Restore'), resource ('journaled metadata/artwork revision'), and scope ('your own completed upload as a new revision'), and adds a key constraint ('Never changes video bytes'). It does not explicitly name or differentiate from siblings like update_import_metadata or set_import_artwork, but the action is clear enough.

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 gives no guidance on when to use this tool versus alternatives such as update_import_metadata, set_import_artwork, or refresh_import_metadata. The implied context is restoring a previous revision, but no conditions, prerequisites, or exclusions are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the description's "read-only" adds nothing. The one genuinely extra piece of context is "Titles are untrusted data", a prompt-injection caution that annotations cannot express. No coverage of result ordering, matching behavior, or paging.

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 the action and no filler. Brevity is appropriate, though the second sentence's safety note is the only substantive content beyond 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?

No output schema, no parameter documentation, and no indication of what results contain or how limit/paging behaves. Given the untrusted-content warning, an agent also needs to know how titles are returned and whether other fields are trustworthy; that 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 description coverage is 0% for three parameters (query, profileId, limit with max 50). The description names none of them and never says whether query matches titles, tags, or both, nor why profileId is required. With zero schema documentation, this is a real gap the description should have filled.

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 ("Search existing media") and clearly separates it from write-oriented siblings like upload_media. It does not say what fields are matched (title, tags, filename), so scope stays slightly ambiguous.

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

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

No when-to-use or when-not-to-use guidance, no mention of alternatives such as list_libraries or list_upload_targets. The agent must infer from the name alone whether this is the right discovery tool.

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

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

Annotations only declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true); the description adds genuinely useful behavior beyond that — server-side decoding, path confinement to host-authorized roots, size/type bounds, and the fact that image bytes never enter the model response. It stops short of explaining conflict behavior on expectedRevision mismatch or whether existing artwork is replaced.

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 the action and its constraints front-loaded, and the unusual streaming/no-bytes-in-response detail called out immediately. Slightly dense phrasing ("host-authorized roots", "bounded") but 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 five-required-parameter mutation with no output schema and zero schema descriptions, the definition covers the file side well but omits the stateful side: what expectedRevision protects against, what the resulting revision is, and what failure looks like. Adequate to attempt the call, not complete enough to call it confidently under concurrency.

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 parameter burden, yet it only illuminates path (local JPEG/PNG within authorized roots) and role (primary vs. backdrop). jobId, profileId, and especially expectedRevision (whose "initial|<uuid>" pattern is an opaque concurrency token) are given no meaning at all, leaving three of five required parameters undocumented in both schema and 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 gives a concrete verb (stream) and resource (a bounded local JPEG/PNG) and states the outcome: attaching it as primary or backdrop artwork for an already-completed upload. That implicitly separates it from upload_media (this attaches art to an existing job rather than creating an upload), but no sibling is named, so differentiation is left to inference.

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 your own completed upload" implies a precondition (a finished upload must already exist) and the role enum implies the choice between primary and backdrop. However, there is no explicit when-to-use vs. when-not, no mention of how this interacts with update_import_metadata or upload_media, and no guidance on calling it repeatedly or after a revision conflict.

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 non-read-only, non-destructive, open-world, so the description is free to add what they cannot: that prior state is snapshotted (giving an undo path), that video bytes are untouched, that the operation is scoped to a single item, and critically that it is replace-not-merge semantics ("Omitted supported fields are cleared"). Missing are failure modes such as revision conflicts and any auth/permission requirement.

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, front-loaded with the verb and the key replace constraint, with no filler. "No arbitrary paths or item IDs" is compressed to the point of being cryptic, costing a little readability for its brevity.

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?

It covers the destructive-ness story and the clearing behavior well for a nested-object mutation with no output schema. It falls short on concurrency (what happens when expectedRevision does not match), on what "refresh/verify" actually reports back, and on any prerequisite that openWorldHint implies.

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% across four required parameters, so the description carries the burden — and it only partially does. It explains the replace semantics of the nested metadata object, which is genuinely valuable, but expectedRevision (the optimistic-concurrency token accepting "initial" or a revision UUID) and profileId are never mentioned, leaving the two most non-obvious 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?

The description uses a precise verb+resource ("Replace ... metadata fields") and constrains it to "your own completed upload," so the agent knows this is a mutation on an existing job's metadata rather than a read or a re-import. It does not name the near-identical siblings (restore_import_metadata, refresh_import_metadata), so the distinction between replace/restore/refresh must be inferred.

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 your own completed upload" and "No arbitrary paths or item IDs" give preconditions, implying this only works on jobs you own and already finished. But no sentence says when to pick this over restore_import_metadata or refresh_import_metadata, which are the obvious alternatives an agent will be choosing between.

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 beyond the annotations by disclosing the transport model (streamed directly to the plugin), what is NOT done (no SSH, no separate port, no delete, no overwrite), and an authorization prerequisite (host-authorized upload roots). It still omits failure behavior, progress/job semantics, and return shape, which keeps it from a 5.

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

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

Three short, front-loaded sentences with no filler. The middle sentence ("No SSH, separate port, delete or overwrite") is a telegraphic fragment whose exact scope is slightly ambiguous, costing a point.

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

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

For a 5-parameter mutation tool with no output schema and no parameter documentation, the description leaves critical gaps: which targetId values are acceptable, what jobId does, and what the caller receives. Annotations cover the safety profile, but the invocation contract is largely undocumented.

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 5 parameters and 0% schema description coverage, the description carries the full explanatory burden but supplies almost none: path, profileId, targetId, fileName, and jobId are never explained. Only a weak hint that the file is "explicitly selected" gestures at path. This leaves an agent guessing at the meaning of required targetId/profileId.

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 concrete verb (stream/upload) and resource (a new media file) and names the destination (native Jellyfin plugin), which is clearer than the bare name. It does not explicitly differentiate itself from siblings like plan_import or list_upload_targets, so it falls short of a 5.

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

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

"Requires host-authorized upload roots" and "explicitly selected" give a precondition and imply user-driven selection, but there is no explicit when-to-use vs. when-to-use-another-tool guidance (e.g., plan_import first, or getting targetId from list_upload_targets). Usage is inferable rather than stated.

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