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

Annotations already establish readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds a genuinely non-obvious behavioral caveat — that an 'enabled' flag does not imply the add-on is actually used or authenticated — which is real context beyond the structured fields.

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 sentence that names the returned fields first and appends the caveat last. Nothing redundant or padded.

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?

An output schema exists, so return-value shape need not be described, and annotations cover the safety profile. The one real gap is the undocumented enabled_only filter, which is minor for an otherwise simple list 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 0% and the description never mentions the single parameter, enabled_only, nor what happens when it is true/false (the default is only in the schema). For a filtering parameter whose behavior defines the result set, this leaves the agent to infer semantics.

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

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

States a specific verb ('List') and resource ('installed add-on IDs, versions and enabled states'), which is more precise than the sibling kodi_status or kodi_addon_settings. It does not explicitly contrast itself with those siblings, 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?

The description gives a caveat ('enabled is not proof of use/authentication') but never says when to reach for this tool versus kodi_status, kodi_addon_settings, or kodi_read. No prerequisites, no exclusions, no alternative 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two pieces of behavioral context: results are 'redacted' and the payload differs based on a 'Manager' context (schema/defaults vs saved XML only). These are meaningful but stated so tersely that an agent cannot confidently act on them.

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

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

It is a single compact sentence with no filler, which is good, but the information density comes at the cost of clarity and it is not front-loaded — the critical scope (active profile, redaction) is buried after a vague verb. It is brief but not efficiently 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?

An output schema exists, so return values need not be described. But four parameters are undocumented in both schema and description, usage is unexplained, and the sibling landscape is not addressed. For a tool in a crowded addon/settings namespace, this leaves an agent without enough to call it correctly.

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%. The words 'Search/page' loosely imply that query/start/limit exist, but none of the four parameters (query, start, limit, addon_id) is explained in the description, and the required addon_id is never mentioned. With zero schema coverage the description should compensate, and it 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 identifies the resource (settings in the active profile) and gestures at a retrieve/page operation, so an agent can infer it reads addon settings. However, the phrasing 'Search/page redacted settings' is cryptic, and it never clearly distinguishes itself from the closely-named sibling kodi_settings or from kodi_set_addon_setting. The 'Manager includes schema/defaults, otherwise saved XML only' clause muddies rather than sharpens the purpose.

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

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

No explicit when-to-use or when-not-to-use guidance is given, and no alternative sibling is named despite several near-identical tools (kodi_settings, kodi_set_addon_setting, kodi_manager_inspect). The only hint is an implicit reference to a 'Manager' variant, which is not framed as a selection condition. Usage is left entirely to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new context: the snapshot is stored privately and locally, and the Shield device itself is not modified, clarifying what the operation does and does not touch.

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 immediately followed by the non-destructiveness constraint. No filler, no repetition of the title.

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

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

An output schema exists, so return values need not be described, and annotations plus the description cover purpose and safety for a one-parameter tool. The remaining gap is practical: it does not say where the snapshot lands or how it is later retrieved or restored.

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 'path' parameter has 0% schema description coverage, so the schema carries no meaning. The description only says it targets 'one Kodi file', leaving unresolved whether the path is device-side, host-side, absolute, or relative — partial but not sufficient compensation.

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 ('Save a ... rollback snapshot of one Kodi file') and the scope ('one Kodi file'), which separates it from bulk siblings like kodi_backups and from the mutating kodi_patch_file/kodi_restore_file. It never names those siblings explicitly, so the differentiation is inferential 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as kodi_backups (listing) or kodi_restore_file (reverting). The 'rollback snapshot' phrasing hints at a backup-before-change workflow but nothing is made explicit.

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

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

Annotations already establish the safe read-only, non-destructive, closed-world profile, so the bar is lower; against that, the description adds real context: results are capped at the latest 50, they are 'private' per-file snapshots, and contents are deliberately not returned (metadata only). It stops short of describing ordering or pagination 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?

A single sentence with no filler: the operation, the result limit, and the data-exposure constraint are all front-loaded in one pass. Nothing is repeated from the schema or annotations verbatim.

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 an output schema present the return shape need not be explained, and with zero parameters there is no input contract to cover, so the description is nearly sufficient. The privacy and 50-item cap are the key behavioral facts an agent needs and both are stated.

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, which is the baseline-4 case; there is nothing for the description to disambiguate and it correctly avoids inventing parameter talk. The 'latest 50' note usefully defines the implicit result window in the absence of any input control.

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 ('List') and resource ('private per-file snapshots') plus scope ('latest 50'), so an agent can distinguish it from kodi_backup_file or kodi_restore_file, which mutate backups. The only wobble is vocabulary drift between the tool name ('backups') and the description ('snapshots'), but intent is still 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?

Usage is only implied: an agent can infer this is how you enumerate available snapshots (presumably before a restore), but the description never says when to choose this over kodi_backup_file or kodi_restore_file, nor states any prerequisite. Adequate minimum, with a clear gap.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, and the description usefully adds that browsing is single-page and non-recursive with no playback side effects. It does not explain why the operation is flagged non-read-only (live provider queries, timeouts, provider wake-up costs), so meaningful behavioral context is still missing.

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 compact clauses with no filler, and the core scope ('Preview one page of actual provider/library folders') is front-loaded. Brevity is a virtue here, though it borders on under-specification.

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?

An output schema exists, so return values need not be described, and the safety profile is partially covered by annotations. Still, for a tool with an unexplained 'path' required argument and underspecified pagination, the description leaves key operational details (path format, 'idle' definition, opt-in mechanism) unclear.

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 the description says nothing about the three parameters. 'one page' hints at pagination, but the meaning/format of 'path', and how 'limit' and 'start' interact, are left entirely undocumented in both places.

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?

Specific verb ('Preview'/'browse') plus resource ('provider/library folders') and an explicit scope limit ('one page'). It also rules out related behaviors ('no recursive loading or playback'), which implicitly separates it from kodi_read and playback tools, though no sibling is named 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?

The clause 'opt-in, idle-only' supplies a precondition for use (must be idle, must be opted in), which is genuine usage context. However, it never says when to choose this over kodi_read, kodi_layout_preview, or other folder-listing siblings, so the guidance 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, and the description adds real context beyond them: the Manager takes a backup before applying and rejects stale revisions, and there is a 10-minute validity window. It does not say exactly which layout state gets overwritten, keeping it short of a 5.

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

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

One tightly packed sentence with the key constraint (10 minutes) and safety behavior front-loaded. The 'Optional Manager:' prefix adds little and is the only wasted token.

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?

An output schema exists so return values need no explanation, and the destructive nature plus backup behavior are covered. However, the essential prerequisite chain (run preview, then apply its id within the window) is only half-stated, which is a meaningful gap for a destructive one-shot operation.

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 required parameter preview_id has 0% schema description coverage, so the description carries the full burden. It refers obliquely to a 'staged plan' but never explains that preview_id comes from kodi_layout_preview or what format it takes.

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 ('apply') and resource ('the exact staged plan'), which is distinguishable from the sibling kodi_layout_preview that creates the plan. The 'Optional Manager:' prefix is ambiguous phrasing, but the core action is unmistakable.

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 10-minute window and stale-revision rejection imply this must follow a fresh preview, but the description never names kodi_layout_preview as the prerequisite or states when not to use it. Usage is inferable rather than explicit.

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

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

Annotations mark this as not read-only but non-destructive, and the description usefully clarifies that no layout write occurs, which slightly reframes those hints. It does add that rows are 'staged' with expected_revision, implying a concurrency check, but gives no detail on side effects, state, 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?

It is a single, terse sentence with no padding, which is good. But the leading 'Optional Manager:' fragment is confusing noise and the front-loaded content is cryptic rather than informative, so brevity comes at the cost of clarity.

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?

An output schema exists, so return values need not be described. However, a nested, undocumented plan object plus a preview operation that is meant to precede apply/rebuild leave significant gaps: the plan contract and the expected workflow are not explained.

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 'plan' parameter is an open object with additionalProperties true and no field docs. The description names two keys, section_id and expected_revision, giving a partial hint, but does not explain the plan's structure or required shape, so it only marginally compensates 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?

The name plus the clause 'no layout write' conveys that this stages a preview of section rows without persisting a layout change, which distinguishes it from kodi_layout_apply. However, the cryptic 'Optional Manager:' prefix and 'stage existing section rows' phrasing are vague about the actual operation, and the distinction from kodi_layout_rebuild or kodi_manager_inspect 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?

There is no explicit guidance on when to call this versus kodi_layout_apply or kodi_layout_rebuild. The 'no layout write' note implies it is a safe dry-run step, but the prerequisite relationship to apply/rebuild is only hinted at, not 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds that the rebuild should happen while idle and that the TV should be inspected afterward, but does not explain what gets destroyed or how disruptive the rebuild is.

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 explanation. The 'Optional Manager:' prefix is slightly odd but does not bloat the description.

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

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

An output schema exists, so return values need not be explained. However, the description does not clarify how this rebuild relates to kodi_layout_apply or kodi_layout_preview, leaving the agent to infer which layout tool to use.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify. Baseline for zero-parameter tools is 4.

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 action: request one skin-menu rebuild. However, the prefix 'Optional Manager:' is ambiguous and does not clearly differentiate this from siblings like kodi_layout_apply or kodi_layout_preview.

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 provides a condition ('while Kodi is idle') and a post-action instruction ('Inspect TV after it finishes'), but does not say when to use this instead of kodi_layout_apply or kodi_layout_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 flag destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond the schema: playback refusal and the permission gate on offline recovery / cross-app interruption, which an agent could not infer from the annotations alone.

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

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

Two tightly packed clauses, front-loaded with the action set and zero filler. The second clause is slightly telegraphic ('Refuses playback') but earns its place by encoding constraints.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. For a destructive lifecycle tool the definition is nearly complete, with the only shortfall being the shallow treatment of the two boolean parameters.

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

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

Schema description coverage is 0%, so the description carries the full param burden. It partially compensates by tying 'offline recovery' and 'other-app interruption' to the two boolean flags and noting they need explicit permission, but it never explains what these modes actually do or the effect of the action enum.

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 leads with specific verbs (start/stop/restart) applied to a clear resource (Kodi), which is easily distinguished from read-oriented siblings like kodi_status and kodi_read. It does not explicitly name a sibling, but the action set 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?

It states a clear 'when-not' ('Refuses playback') and the governing condition for the advanced flags (offline recovery / interrupting another app require explicit permission). It gives operational context but names no concrete alternative tool for those scenarios.

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=false, so 'safe while viewing' largely restates what is structured. The word 'redacted' adds genuine value by telling the agent returned log content has secrets stripped, but truncation/tail behavior and what 'previous' does are not disclosed.

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

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

A single tight sentence with the action and resource front-loaded and no filler. It is efficient, though the compressed 'crash/stream/storage signals' phrasing is terse to the point of being slightly opaque.

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?

An output schema exists, so return values need no explanation, and the tool is low-complexity with two optional params. Still, the undocumented 'previous' flag and absent sibling routing leave real gaps for an agent choosing between this and shield_logcat / kodi_read.

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%: neither 'lines' nor 'previous' has any schema-level description. The phrase 'log tail' loosely implies the line-count parameter but never names it, and 'previous' (read the rotated/prior log) is entirely 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?

States a specific verb ('Inspect') and resource ('redacted Kodi log tail and crash/stream/storage signals'), so an agent knows exactly what is returned. It does not, however, differentiate itself from the near sibling shield_logcat or explain how it relates to kodi_status/kodi_read.

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?

'safe while viewing' is a safety reassurance, not usage guidance. There is no statement of when to pick this tool over shield_logcat or the other kodi readers, and no explanation of the 'previous' scenario (e.g. use when the current log is empty/rotated).

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=false, so the safety profile is covered. The description adds only the mild contextual fact that it inspects 'saved' state, and says nothing about auth needs, scope limits, or what a health/fix inspection actually reports. With rich annotations the lower bar applies, so a baseline 3 fits.

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 compact sentence, which is good, but it is front-loaded with noise ('Optional Kodi Manager 0.3.9:') that does not help selection and crowds out the actual scope 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?

An output schema exists so return values need not be described, and there is only one enum parameter. However, for a five-way inspection tool sitting among many kodi_* siblings, an agent still lacks guidance on what each area inspects and when to prefer this over kodi_status or kodi_layout_preview.

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

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

Schema description coverage is 0%, so the description must carry the load. It partially compensates by naming hubs/rows, sources, pipeline, health and fix status, but the mapping to enum values is loose ('fixes' vs 'fix status', 'layout' vs 'Bingie hubs/rows') and no meaning is given for what each area returns or which to choose.

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 enumerates the resources covered (Bingie hubs/rows, sources, pipeline, health, fix status), which aligns with the area enum. It is clear what the tool does, but it never distinguishes itself from look-alike siblings such as kodi_status or kodi_layout_preview.

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 only hint is the word 'Optional' and an implicit list of areas; there is no statement of when to reach for this tool versus kodi_status, kodi_layout_preview, or kodi_browse, and no prerequisites or exclusions are given.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description adds genuinely new behavior: Kodi must be stopped, the SHA must match, and a backup is taken automatically. It omits that dry_run defaults to true, which is the most important operational detail.

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 compact sentences with no filler, and the preview/apply scope is front-loaded ahead of the write constraints. Very dense but readable; no wasted clauses.

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?

Output schema exists so return values need no explanation, and the write hazards are covered. However, with four undocumented parameters, a nested edits array of unexplained shape, and a default-true dry_run never mentioned, an agent lacks enough to call it confidently.

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

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

Schema description coverage is 0%, so the description carries the full burden. It maps to three params (before/after replacements -> edits, matching SHA -> expected_sha256, preview/apply -> dry_run) but says nothing about path semantics or the shape of the edits array entries.

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 (patch) and resource (file) plus the mechanism: exact before/after replacements with preview or apply. This distinguishes it from kodi_read_file and kodi_backup_file, though it doesn't explicitly name siblings.

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

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

Gives the key precondition for writes (Kodi must be stopped) and implies the preview-vs-apply choice, but never names alternatives (e.g., kodi_restore_file, kodi_backup_file) or states when a patch is preferable to editing via settings 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, destructiveHint:false and openWorldHint:false, so the safety profile is covered. The description adds material behavioral context beyond that: queries are restricted to an allowlist and arbitrary/execution-style methods are rejected, which tells the agent a rejection is possible for out-of-scope methods.

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 positive capability and immediately followed by the constraint. No filler, no repetition of the name.

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

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

An output schema exists, so return values need not be described. But with 0% parameter coverage and no list or example of valid allowlisted methods, an agent cannot reliably select a valid 'method' argument — the definition is thin for a two-parameter dispatcher.

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 both 'method' and 'params' are undocumented structurally. The description only implies 'method' is a JSON-RPC method name and does not enumerate allowable methods or explain the params object shape, leaving the agent without the information needed to supply valid inputs.

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: 'Run an allowlisted diagnostic JSON-RPC query,' with a stated scope (allowlisted, diagnostic). This distinguishes it from generic RPC execution, though it does not differentiate it from siblings like kodi_status, kodi_logs, or kodi_browse that also read diagnostics.

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

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

The second sentence gives negative guidance — 'No arbitrary RPC, executebuiltin or playback calls' — which tells the agent the tool's boundaries, a partial form of when-not-to-use. However, there is no positive when-to-use context and no pointer to which sibling handles the excluded operations.

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=false, so the safety profile is covered. The description adds real behavioral detail (600 KB size cap, redaction applied, SHA-256 of the original returned), but leaves opaque what redaction actually removes and what happens when a file exceeds the cap.

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 zero filler; the verb and resource come first and the constraints follow.

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?

An output schema exists, so return values need not be spelled out. For a simple read tool the description is largely adequate, but it omits failure behavior (oversized files, missing files, non-text targets) and does not disambiguate from the many sibling reader tools.

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 the single 'path' parameter has no schema description, so the description must compensate. 'Kodi-relative text file' usefully conveys that the path is relative to the Kodi installation and must point at a text file, but gives no syntax, extension, or error-handling detail.

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 (Read) and resource (Kodi-relative text file) plus notable constraints: 600 KB max, redaction, SHA-256. It is clear what the tool does, though it never differentiates itself from close siblings like kodi_read, kodi_logs, or kodi_browse.

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 at all. With siblings such as kodi_read, kodi_browse, and kodi_logs present, the agent gets no signal about when this file reader is the right choice versus those alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds real value beyond that: a required precondition (Kodi stopped), a validation behavior (stale checksums rejected), and a mitigating side effect (undo snapshot created). It stops short of noting auth requirements or irreversibility of the undo snapshot.

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 dense sentence, front-loaded with the operation, then precondition, validation, and side effect in order of importance. 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?

For a destructive mutation with an output schema present, the description covers precondition, validation, and rollback safety. The only gap is that backup_id's expected form is never clarified.

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 compensate. 'Rejects stale checksums' does explain the role of expected_current_sha256 as a concurrency guard, but backup_id is left undefined (id format, where it comes from), so compensation is only partial.

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) and resource (one snapshot), and its scope ('one') cleanly separates it from kodi_backups and kodi_backup_file. An agent can identify the 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?

Gives a clear precondition ('while Kodi is stopped') that tells the agent when the call is valid, but names no alternatives (e.g., when to back up instead of restore) or exclusions beyond the stale-checksum rejection.

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

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

Adds real behavior beyond the annotations: the change is 'backed up' (mitigating the destructiveHint), restricted to non-credential settings, gated on a 'verified' version, and requires Kodi to be stopped when no Manager is present. The backup and stop-first facts are not derivable from the structured fields. It stops short of describing reversibility or what the output reports.

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 compact clauses, front-loaded with the core action. 'backed up' is a fragment that reads telegraphically, but no sentence is wasted.

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

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

Output schema exists so return values need no explanation, and the description covers backup, scope, and the stop-Kodi prerequisite. The significant gap is the 0%-documented parameter set, which leaves the definition incomplete for a mutation tool with four required arguments.

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 4 required parameters, so the description must carry the load. It only hints at expected_version ('verified ... version') and setting ('non-credential'); addon_id and value formats are left entirely unexplained, so the agent gets little help with the arguments.

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

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

States a specific verb+resource ('Change a ... setting on ... add-on') with meaningful scope qualifiers ('non-credential', 'verified add-on version'). It is distinguishable from the sibling kodi_set_setting, though the description never names that sibling explicitly, so differentiation is implicit 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?

Provides one conditional prerequisite ('Without Manager, stop Kodi first') that tells the agent when extra steps are needed. However, it never states when to choose this over kodi_set_setting or kodi_addon_settings, and there are no exclusions beyond 'non-credential'.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation nature is covered. The description adds valuable behavioral context beyond annotations: it performs the change via a runtime API, creates a guisettings.xml rollback snapshot, and is limited to non-credential settings. This meaningfully helps the agent understand the operation's safety profile and scope.

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 that packs the essential action, scope, and behavioral note without any wasted words. It is appropriately sized for the tool's complexity.

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?

An output schema exists, so return values need not be explained, and annotations already cover the safety profile. The description adds key operational context (runtime API, rollback snapshot, non-credential scope), but it leaves a significant gap around parameter semantics since the schema provides no parameter descriptions. An agent still lacks guidance on how to supply valid 'setting' and 'value' inputs.

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 parameter semantics. It only implies that 'setting' must be a non-credential Kodi setting and that 'value' is whatever is being changed, but it gives no format guidance, examples, or constraints for either parameter. The agent cannot infer valid setting names or value types from 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 states a specific verb ('Change') and resource ('Kodi setting'), and adds scoping details like 'non-credential' and 'runtime API' that separate it from sibling tools such as kodi_set_addon_setting and kodi_patch_file. However, it does not explicitly name or compare against an alternative sibling, so it falls short of the top score.

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 context by specifying that it is for 'non-credential' Kodi settings through the 'runtime API,' which helps an agent understand when it might apply. But it gives no explicit when-to-use guidance, no exclusions, and no named alternatives for cases where a different tool would be better.

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=false, so the safety profile is covered. The description adds that results carry current and default values, which is genuine behavioral context, but says nothing about pagination behavior, query semantics, or result size 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 sentence with no filler; the purpose comes first and the rationale trails. It is slightly terse for a tool with three undocumented parameters, but nothing is wasted.

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

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

An output schema exists, so return-value explanation is not required, and the read-only annotations cover safety. Still, for a 3-parameter search tool at 0% schema coverage, the description leaves query and paging semantics under-specified.

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

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

Schema description coverage is 0%, so the description must carry the load. 'Search/page' does map meaningfully onto the three params (query = search term, limit/start = paging), giving partial compensation, but it never clarifies query matching syntax, limit bounds, or start offset semantics.

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

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

States a specific verb (search/page) and resource (Kodi's expert settings) plus what is returned (current/default values). The phrase 'expert settings' implicitly distinguishes it from the sibling kodi_addon_settings / kodi_set_setting, though it never names an alternative 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 clause 'avoiding a whole-schema dump' implies this is the lightweight, filtered alternative to reading the full schema, which is useful implied usage guidance. However, no explicit when-to-use condition or named alternative tool is given, so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by enumerating what is inspected (version, skin, profile/window, active players) and explicitly ruling out playback changes, which goes beyond the annotations. It stops short of describing return format or latency, but the output schema exists to cover 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?

A single, front-loaded sentence that names the verb, the inspected fields, and the key constraint. Every clause earns its place with 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 zero-parameter, read-only status tool with a rich output schema and full annotations, the description is nearly complete. It covers purpose, exclusions, and inspection targets. A minor gap is the absence of explicit routing to sibling read tools, but the core call requirements are met.

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 the baseline is 4. The description correctly focuses on the return scope rather than parameters, which is appropriate. No parameter semantics are needed or missing.

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?

Clear verb ('Inspect') and resource (Kodi state: version, skin, profile/window, active players). It is distinguishable from siblings like kodi_manager_inspect and kodi_lifecycle, though it does not explicitly name those alternatives. The scope is specific enough that an agent can tell what it returns 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 phrase 'no playback changes' implies a read-only, non-mutating context, which hints at when to use it versus mutating siblings (kodi_playback controls, kodi_settings). However, it does not explicitly state when to choose this over similar read tools like kodi_manager_inspect or kodi_read. Usage is implied, not spelled out.

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=false, so safety is covered. The description still adds a real disclosure beyond them: it returns only package names and explicitly excludes app/account data, which is useful scope information for an agent deciding what data it can rely 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?

A single sentence, front-loaded with the action and resource, with the scope qualifier in parentheses. Nothing is wasted and nothing is buried.

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

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

For a zero-parameter read tool with an output schema, the description covers purpose and data scope adequately; return-value detail is legitimately left to the output schema. The only omission is whether a connected device is required.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed, and there are no parameter semantics to explain.

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 specific verb and resource ('List installed Android package names'), which is immediately distinguishable from sibling read tools like shield_status or shield_screenshot. The parenthetical scope note further narrows intent, though it does not explicitly name a sibling it should be preferred over.

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 guidance on when to call this versus alternatives such as shield_status or shield_connect, nor any prerequisite (e.g., an active device connection). The agent must infer the usage context entirely.

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 mutation and open-world profile is covered. The description adds genuinely useful context not in the annotations: it requires physically accepting a debugging prompt on the TV. It does not mention state changes, failure modes, or prerequisites like ADB availability.

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, no redundancy, with the core action front-loaded and the TV-side prerequisite immediately after. Every sentence earns its place.

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

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

With an output schema present, return values need not be described, and annotations cover the safety profile. The description supplies the key operational prerequisite (accepting the TV debugging prompt), leaving only minor gaps such as what happens on connection failure or whether an existing session is reused.

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 per the rubric the baseline is 4. Schema coverage is 100% and there is nothing further the description could clarify about inputs.

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 ('Connect ADB') and resource ('the configured Shield') plus a scoping constraint ('only'), so it is easily distinguished from read-oriented siblings like shield_status or shield_remote. It stops short of naming an alternative or contrasting with the other shield_* 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?

'Only' hints that this is the sole connection path, and the TV-prompt sentence implies a first-run/precondition context. There is no explicit when-to-use vs. when-not guidance or reference to a sibling for a related task, 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 the safe read-only profile, and the description adds two pieces of genuinely useful context: output is 'bounded' (limited tail) and 'Redaction is best effort', warning the agent that sensitive data may not be fully masked. It stops short of stating the actual bound or whether truncation is signalled.

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

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

Two short sentences with no filler; the core purpose is front-loaded and the caveat follows. Nothing could be removed without losing 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?

An output schema exists, so return values need no explanation, and the annotation covers the safety profile. The remaining gap is the undocumented 'lines' parameter and any connection precondition, which a one-param read tool should still address.

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 'lines' parameter (default 150) is documented only by its title and default. The description's 'bounded log tail' implies a line-count limit but never ties it to the parameter or explains the tail direction or maximum allowed value.

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?

Specific verb (Read) plus resource (Android log tail) and scope qualifier (bounded), with a stated use case (native crashes). It is distinguishable from the kodi_* log/read siblings by naming the Android platform, though it does not explicitly contrast with them.

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

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

The phrase 'for native crashes' implies a narrow use case, but there is no explicit when-to-use guidance, no mention of alternatives (e.g. shield_status for general diagnostics), and no prerequisites such as needing an active 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 destructiveHint=true and readOnlyHint=false. The description adds a genuine behavioral constraint beyond structured data — playback buttons are gated on permission and write mode — but does not explain what is destroyed, whether allow_during_playback bypasses the gate, or any rate/confirmation 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?

Two tight sentences, zero filler, with the action front-loaded and the precondition second. Every clause earns its place.

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

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

The presence of an output schema removes any need to describe return values. Still, for a destructive, permission-gated remote-control tool with zero parameter documentation, the definition leaves key operational details (the allow_during_playback flag, what the destructive hint applies to) 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 0%, so the description carries the full burden for two parameters. The button enum self-documents its values, but 'allow_during_playback' is never mentioned, and the description's 'write mode' wording does not clarify how that flag interacts with the gating rule.

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 ('Send one explicit remote button'), making the action unambiguous. It does not differentiate itself from the many shield_*/kodi_* siblings, but the purpose itself is clear 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?

'Send one explicit remote button' implies single-action usage, and 'Playback controls require permission and write mode' gives a real precondition. However, it never says when to prefer this tool over alternatives such as shield_status or the kodi_* controls, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new context beyond that: it does not navigate or change device state, and screens may expose private information, which is a real operational caveat for an agent deciding whether to capture and surface the image.

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, zero filler, with the core action front-loaded and the privacy caveat right behind it. Nothing could be cut without losing meaning.

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

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

For a zero-param read tool with full annotation coverage this is close to complete, but there is no output schema, so the description is the only place that could say what a caller actually receives (base64 image, file path, dimensions). That gap is minor but real for a screenshot 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 has zero parameters, so the baseline of 4 applies. The description correctly says nothing about arguments, avoiding noise.

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 ("Capture the current TV screen") and adds a scoping qualifier ("without navigation") that tells the agent the screen state is not altered. It is not confused with any sibling, since none of shield_status/shield_connect/shield_logcat/etc. capture a screen, though it never explicitly distinguishes itself from them.

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

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

Usage is only implied: "without navigation" hints the tool is for reading the current screen rather than driving the UI, but there is no statement of when to prefer this over shield_status or shield_apps, nor any precondition. An agent can infer intent but gets no routing help.

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=false, so the safety profile is covered by structured data. The description adds which data domains are surfaced (model, Android version, memory, storage, Kodi process), but says nothing about auth requirements, cost, or freshness/latency.

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 verb and the full list of inspected items front-loaded. Every word earns its place and there is no boilerplate.

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 an output schema present, return values need not be explained, and with zero parameters the input side is trivially complete. The description covers the scope of inspection adequately, though it omits any dependency on shield_connect having run first.

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 are no argument semantics to document; the baseline of 4 applies. The description's enumeration of returned fields is a bonus rather than a compensation for a 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 ('Inspect') plus the resource and enumerates exactly what is retrieved: Shield model, Android version, memory, free storage, and Kodi process. It is clearly distinguishable from the Kodi-only siblings such as kodi_status, though it does not explicitly name them.

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

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

There is no statement of when to call this rather than kodi_status, kodi_manager_inspect, or shield_connect, and no prerequisites (e.g., must the device be connected first). Usage is only implied by the word 'Inspect'.

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