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

With no annotations, the description carries full burden. It mentions the tool returns immediately with a job ID, which is useful context about asynchronous behavior. However, it lacks critical details like whether this is a destructive operation (e.g., modifies the disc), permission requirements, or error handling.

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 extremely concise with two sentences that are front-loaded and waste no words. Every sentence adds value: the first states the purpose, and the second clarifies the asynchronous nature.

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 no annotations, 0% schema description coverage, and an output schema (which helps with return values), the description is incomplete. It lacks parameter explanations, usage context, and behavioral details like side effects or error conditions, making it inadequate for safe and effective 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?

Schema description coverage is 0%, and the description provides no information about parameters. The input schema defines 'drive_index' and 'output_dir', but the description doesn't explain their purpose, usage, or constraints, failing to compensate for the lack of schema descriptions.

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 clearly states the action ('Full disc backup') and resource ('disc'), distinguishing it from siblings like 'rip_title' or 'scan_disc'. However, it doesn't explicitly differentiate from 'rip_all', which might also involve backing up content.

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

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

No guidance is provided on when to use this tool versus alternatives like 'rip_all' or 'rip_title'. The description mentions it 'Returns immediately with a job ID', but this doesn't clarify usage context or prerequisites.

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

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

Annotations provide 'destructiveHint: true,' indicating a mutation operation. The description adds value by specifying the target ('queued or running rip job'), which clarifies the scope of the destructive action. It doesn't contradict annotations, and it offers useful context beyond the structured data.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It's front-loaded and appropriately sized for the complexity of the tool.

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

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

Given the tool's moderate complexity (one parameter, destructive operation) and the presence of an output schema (which handles return values), the description is reasonably complete. It covers the core action and target, though it could benefit from more detailed usage guidelines or behavioral context to be fully comprehensive.

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%, with one parameter ('job_id') documented only in the schema. The description doesn't add any parameter-specific information beyond what's implied by the tool name. However, with only one parameter, the baseline is higher, and the description's general context partially compensates for the lack of detailed param 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?

The description clearly states the action ('Cancel') and the target ('a queued or running rip job'), providing specific verb+resource information. However, it doesn't explicitly differentiate from sibling tools like 'makemkv_job_status' or 'makemkv_list_jobs' beyond the cancel action itself.

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 'queued or running rip job,' suggesting when this tool is applicable. However, it doesn't provide explicit guidance on when to use it versus alternatives (e.g., 'makemcv_job_status' for checking job state) or any prerequisites, leaving some gaps in usage clarity.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('eject disc') but lacks details on permissions, side effects (e.g., if the drive becomes unavailable after ejection), or error conditions. This is a significant gap for a tool that performs a physical operation.

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, direct sentence with zero waste—it states the action and the parameter context efficiently. It's front-loaded and appropriately sized for a simple tool, earning full marks for conciseness.

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

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

Given the tool's low complexity (one parameter) and the presence of an output schema, the description is minimally adequate. However, with no annotations and a physical operation involved, it should ideally include more behavioral context (e.g., safety warnings or prerequisites) to be fully 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?

The description adds meaning by specifying that the parameter is for 'the specified drive', which clarifies the purpose of the 'drive_index' parameter. With 0% schema description coverage and only one parameter, this compensation is effective, though it doesn't detail format or constraints beyond what's implied.

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 clearly states the verb ('eject') and resource ('disc from the specified drive'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'makemkv_cancel_job' or 'makemkv_list_drives', which might also involve drive operations, so it doesn't reach the highest 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 provides no guidance on when to use this tool versus alternatives. For example, it doesn't mention prerequisites like needing a disc to be present or when to use it in relation to sibling tools such as 'makemkv_rip_all' or 'makemkv_scan_disc'. This leaves the agent with insufficient context for optimal tool selection.

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

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

The description adds value beyond the readOnlyHint annotation by specifying the output format ('as YAML'), which is not covered by annotations. It doesn't contradict annotations (readOnlyHint=true aligns with 'Get'), and while it could mention more about behavior like response structure or errors, it provides useful context for a read operation.

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, clear sentence with no wasted words, front-loading the key information ('Get current server configuration as YAML'). It's efficiently structured and easy to parse, making it highly concise.

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

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

Given the tool's simplicity (one parameter with no properties, read-only operation, and an output schema exists), the description is reasonably complete. It specifies the output format, which complements the output schema, though it could briefly mention the tool's role relative to 'makemkv_set_config' for better context.

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 0% schema description coverage and only one parameter ('input') that has no properties, the description doesn't need to explain parameters. It appropriately focuses on the tool's purpose, and since there are effectively zero meaningful parameters, it compensates well by clarifying the output format, earning a high baseline score.

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 clearly states the action ('Get') and resource ('current server configuration') with a specific format ('as YAML'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from its sibling 'makemkv_set_config' beyond the obvious get/set distinction, which keeps it from a perfect 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 provides no guidance on when to use this tool versus alternatives like 'makemkv_set_config' for configuration management, nor does it mention any prerequisites or context for retrieving configuration. It's a basic statement of function without usage context.

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

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

Annotations provide readOnlyHint=true and idempotentHint=true, indicating safe, repeatable reads. The description adds context about checking 'status and progress,' which suggests it returns dynamic job information, but doesn't detail rate limits, auth needs, or specific behavioral traits like error handling. No contradiction with annotations exists.

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, efficient sentence that front-loads the core action ('Check the status and progress') without unnecessary words. Every part earns its place by directly conveying the tool's function.

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

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

Given the tool's low complexity (one parameter), annotations covering safety, and an output schema (which handles return values), the description is reasonably complete. It could improve by mentioning the job ID parameter or error cases, but it adequately supports agent usage in this context.

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 0% schema description coverage (parameter 'job_id' has minimal description), the description compensates by implying the parameter's purpose ('rip job'), but doesn't specify format or constraints. Since there's only one parameter, the baseline is high, and the description adds some meaning beyond the schema, though not exhaustively.

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 clearly states the verb ('Check') and resource ('status and progress of a rip job'), making the purpose evident. It distinguishes from siblings like 'makemkv_list_jobs' (which lists jobs) and 'makemkv_cancel_job' (which cancels jobs) by focusing on status/progress of a specific job. However, it doesn't explicitly mention the job ID parameter, which could enhance specificity.

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

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

The description implies usage when needing to check a rip job's status, but doesn't explicitly state when to use this vs. alternatives like 'makemkv_list_jobs' (for listing all jobs) or 'makemkv_monitor' (which might monitor ongoing jobs). No exclusions or prerequisites are mentioned, leaving some ambiguity in context.

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

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

Annotations indicate read-only and idempotent operations, which the description does not contradict. The description adds value by specifying that it lists drives and their disc status, providing context on what information is returned. However, it lacks details on potential errors, rate limits, or authentication needs, though annotations cover safety aspects.

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, clear sentence that directly states the tool's function without unnecessary words. It is front-loaded with the core action and resource, making it efficient and easy to understand at a glance.

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

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

Given the tool's low complexity (one parameter, read-only/idempotent annotations, and an output schema), the description is complete enough. It specifies what the tool does, and the output schema handles return values, so no additional details are needed for effective 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?

With 0% schema description coverage, the description does not mention the 'response_format' parameter. However, since there is only one parameter and an output schema exists, the description's focus on the tool's purpose compensates adequately. It does not add parameter details, but the minimal parameter count and output schema reduce the need for extensive parameter explanation.

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 clearly states the verb ('List') and resource ('optical drives and their disc status'), making the purpose specific and unambiguous. It distinguishes itself from siblings like 'makemkv_scan_disc' (which scans disc contents) or 'makemkv_list_jobs' (which lists jobs), as it focuses on hardware drives and their status.

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 for checking drive availability and disc presence, but does not explicitly state when to use this tool versus alternatives like 'makemkv_scan_disc' for disc content or 'makemkv_list_jobs' for job status. No exclusions or prerequisites are mentioned, leaving usage context somewhat inferred.

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 idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds minimal behavioral context beyond this—it mentions 'recent' jobs and 'optional status filter,' but doesn't clarify what 'recent' means (e.g., time range, pagination) or other traits like rate limits or authentication needs. No contradiction with annotations exists.

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, efficient sentence: 'List recent rip jobs with optional status filter.' It's front-loaded with the core action and includes key details without unnecessary words, making it easy to parse quickly.

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

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

Given that annotations cover safety (read-only, idempotent) and there's an output schema (so return values are documented elsewhere), the description is moderately complete. However, it lacks details on usage context, behavioral nuances (e.g., what 'recent' entails), and differentiation from siblings, leaving gaps for an agent to fully understand when and how to invoke it.

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%, but the description mentions 'optional status filter,' which aligns with the 'status_filter' parameter in the schema. However, it doesn't explain the 'limit' parameter or provide additional semantic context beyond what's implied. With one parameter documented in the schema and the description adding some value, a baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'List recent rip jobs with optional status filter.' It specifies the verb ('List'), resource ('recent rip jobs'), and scope ('optional status filter'), but doesn't explicitly differentiate it from sibling tools like 'makemkv_job_status' or 'makemkv_monitor' that might also provide job-related information.

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 provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'makemkv_job_status' (which might get details for a specific job) or 'makemkv_monitor' (which might provide real-time updates), nor does it specify prerequisites or appropriate contexts for listing jobs versus other 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions actions but doesn't detail effects like whether starting the monitor requires specific permissions, if it runs continuously, what happens on errors, or how status checks return data. This is inadequate for a tool that controls a monitoring process.

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, efficient sentence that front-loads the key actions without any wasted words. It directly communicates the tool's functionality in a clear and structured manner, making it easy to parse quickly.

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

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

Given the tool's moderate complexity (controlling a monitor) and the presence of an output schema (which handles return values), the description is minimally adequate. However, with no annotations and incomplete behavioral details, it doesn't fully cover aspects like error handling or operational constraints, leaving gaps in context.

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 description adds no parameter semantics beyond what the input schema provides. Schema description coverage is 0%, but the schema itself includes a clear enum description for 'action' (start, stop, status), which compensates somewhat. Since there's only one parameter, the baseline is 4, but the description fails to add any value, so it's scored lower.

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 clearly states the tool's purpose with specific verbs ('Start, stop, or check') and resource ('drive auto-rip monitor'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'makemkv_rip_all' or 'makemkv_rip_title' that might also involve ripping operations, preventing a perfect 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 provides no guidance on when to use this tool versus alternatives. For example, it doesn't explain if this should be used before or after ripping tools, or how it relates to monitoring versus job status tools like 'makemkv_job_status'. This lack of context leaves the agent to infer usage 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool 'Returns immediately with a job ID,' which is useful for understanding it's an asynchronous operation. However, it lacks details on permissions, rate limits, error handling, or what the job ID is used for (e.g., with 'makemkv_job_status').

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 highly concise with two sentences that are front-loaded and waste no words. Each sentence adds value: the first states the action, and the second explains the return behavior.

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

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

Given the complexity of an asynchronous ripping operation with 1 parameter (nested with 3 properties) and no annotations, the description is incomplete. It lacks parameter explanations, usage context, and behavioral details like error handling. While an output schema exists (implying return values are documented elsewhere), the description doesn't adequately cover the tool's full scope.

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

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

The schema description coverage is 0%, meaning parameters are undocumented in the schema. The description provides no information about the 'input' parameter or its nested properties (drive_index, output_dir, min_duration), failing to compensate for the schema gap. This leaves parameters completely unexplained.

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

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

The description clearly states the action ('Start ripping all titles from disc') and resource ('disc'), making the purpose specific and understandable. It distinguishes from sibling 'makemkv_rip_title' by specifying 'all titles' versus a single title, though it doesn't explicitly name the alternative.

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

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

No guidance is provided on when to use this tool versus alternatives like 'makemkv_rip_title' for specific titles or 'makemkv_backup_disc' for backup operations. The description lacks context about prerequisites, such as needing a disc in the drive or using 'makemkv_list_drives' first.

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

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

With no annotations, the description carries full burden but only mentions that it 'Returns immediately with a job ID'. It doesn't disclose behavioral traits like whether it's destructive (likely writes files), requires specific permissions, has rate limits, or what the job ID is used for (e.g., monitoring with 'makemkv_job_status'). This leaves significant gaps for a mutation tool.

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, efficient sentence that front-loads the core action and key behavioral note (immediate return with job ID). There is no wasted verbiage, making it highly concise and well-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?

Given a mutation tool with no annotations, 0% schema coverage, and an output schema (which might describe the job ID), the description is incomplete. It lacks details on parameters, behavioral implications (e.g., file system changes), and integration with sibling tools like 'makemkv_job_status', making it inadequate for safe and effective 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?

Schema description coverage is 0%, so the description must compensate but adds no parameter information. It doesn't explain what 'title_index' or 'drive_index' mean, what 'output_dir' defaults to, or how to determine valid values. This fails to address the undocumented parameters, leaving semantics unclear.

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 clearly states the action ('Start ripping') and resource ('a single title from disc'), distinguishing it from sibling tools like 'makemkv_rip_all' which rips all titles. However, it doesn't specify what 'ripping' entails (e.g., extracting video content), leaving some ambiguity.

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 for single-title ripping versus 'makemkv_rip_all' for all titles, but lacks explicit guidance on prerequisites (e.g., disc must be scanned first) or when to use alternatives like 'makemkv_backup_disc'. It provides basic context but no exclusions or detailed comparisons.

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 indicate read-only and idempotent operations, which the description doesn't contradict. However, the description adds minimal behavioral context beyond this—it mentions scanning for specific data types but doesn't cover aspects like execution time, error handling, or dependencies on disc presence. With annotations providing safety hints, the description adds some value but lacks depth.

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, efficient sentence that front-loads the core action ('Scan a disc') and lists key outputs. There is no wasted verbiage, making it highly concise and well-structured for quick understanding.

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

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

Given the tool's low complexity (one parameter, simple scanning operation), annotations covering safety, and the presence of an output schema, the description is reasonably complete. It specifies what data is scanned for, which aligns with the tool's purpose. However, it lacks details on usage context or parameter meanings, leaving minor gaps.

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

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

Schema description coverage is 0%, meaning parameters are undocumented in the schema. The description doesn't mention any parameters, so it adds no semantic information beyond what the schema provides. However, with only one parameter (a nested object with two fields), the baseline is moderate as the tool is simple, but 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?

The description clearly states the tool's purpose with a specific verb ('Scan') and resource ('a disc'), listing what it scans for ('titles, streams, durations, and sizes'). It distinguishes from siblings like 'makemkv_list_drives' (which lists drives) or 'makemkv_rip_title' (which rips content), though it doesn't explicitly contrast 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?

No guidance is provided on when to use this tool versus alternatives. For example, it doesn't mention prerequisites like needing a disc inserted or how it differs from 'makemkv_list_drives' for drive information. The description only states what it does, not when it's appropriate.

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?

No annotations are provided, so the description carries the full burden. It discloses that updates are 'not persisted to disk', which is a key behavioral trait, but lacks details on permissions needed, whether changes are reversible, error handling, or rate limits. For a mutation tool with zero annotation coverage, this is insufficient.

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, efficient sentence that front-loads the core action and adds a critical behavioral detail ('not persisted to disk') 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?

Given that there is an output schema (which should cover return values), the description's main gap is the lack of parameter explanation and insufficient behavioral details for a mutation tool. It covers the transient nature but misses other aspects like error conditions or usage context, making it minimally adequate but incomplete.

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 description does not mention any parameters, while the input schema has 1 parameter with 0% description coverage (the schema's 'input' property lacks a description). Since schema coverage is low, the description fails to compensate by explaining what 'input' entails, leaving parameters largely undocumented. The baseline is adjusted due to low coverage, but no value is added.

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

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

The description clearly states the action ('Update a config value') and specifies the resource ('config value'), with the additional detail 'at runtime (not persisted to disk)' distinguishing it from persistent configuration changes. However, it doesn't explicitly differentiate from sibling tools like 'makemkv_get_config', which is a read operation, though the verb 'Update' implies a write operation.

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 provides no guidance on when to use this tool versus alternatives, such as 'makemkv_get_config' for reading config values or other tools for related tasks. It mentions the runtime nature but doesn't specify prerequisites, exclusions, or typical scenarios for usage.

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