Handover

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

The description adds meaningful behavioral context by identifying the tool as a legacy compatibility mutation, which goes beyond the annotations that only indicate mutation (readOnlyHint=false). It does not contradict annotations and explains the intended usage context, though it does not detail side effects or permissions.

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 two sentences, with the primary purpose front-loaded and the usage recommendation concisely stated. There is no redundancy or unnecessary information.

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

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

For a simple create mutation, the description fully conveys the purpose, the legacy context, and the recommended alternative. It provides sufficient context for an agent to decide when to use the tool and what it does.

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

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

The input schema provides 100% coverage of all three parameters with descriptions, so the description does not need to add parameter details. The description does not mention parameters, but the schema is sufficient, warranting the 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 tool creates a work request in a product Space with the specific verb 'creates' and resource. It also distinguishes from siblings by labeling it as a 'Legacy Reporter compatibility mutation' and referencing an alternative, making its purpose unambiguous.

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

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

The description explicitly recommends handover.requests with action=create for new integrations, which tells the agent when not to use this tool. The legacy context implies its use is for existing Reporter integrations, providing clear guidance.

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

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

Annotations are all false, offering minimal behavioral insight. The description adds that this is a mutation and legacy-specific, but does not disclose return values, duplicate handling, or permission requirements. It does not contradict annotations, and some context is provided, so it meets the minimum viable level.

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 two sentences: the first states the core purpose, the second gives an explicit alternative. It is front-loaded, concise, and contains no unnecessary wording.

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 tool is simple with three parameters, no output schema, and clear core purpose plus alternative. The description covers usage and legacy status well. However, with no output schema, it would be beneficial to state what the tool returns or error behavior, which is missing. This small gap prevents a perfect score.

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

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

Schema description coverage is 100%, with all three parameters (name, slug, description) already having clear descriptions. The tool description adds no additional parameter semantics beyond what the schema provides, so the 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 states the specific action 'creates a product Space' and distinguishes itself as a legacy Reporter compatibility mutation, explicitly naming the preferred alternative handover.spaces. This makes the purpose clear and differentiates it from siblings.

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

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

The description explicitly instructs to prefer handover.spaces with action=create for new integrations, providing clear guidance on when to use this tool (legacy compatibility only) versus the alternative. This is an excellent usage guideline.

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 that deletion is permanent and that this is a compatibility mutation rather than the recommended path. It does not describe response or side effects, but for a single-item delete the added context is sufficient.

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

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

Two sentences with no filler. The first sentence front-loads the action and target, and the second sentence gives a compact alternative preference.

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

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

For a simple one-parameter delete with strong annotations and a fully descriptive schema, the description is complete. It also provides the legacy context and alternative recommendation, which is valuable contextual guidance.

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 covers 100% of the single parameter with a pattern and description ('Request identifier returned by list_backlog'), so the tool description does not need to add parameter-level detail. The description's reference to 'one work request' only lightly reinforces the schema.

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

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

The description names a specific verb ('permanently deletes') and a specific resource ('one work request'), and labels it as a 'Legacy Reporter compatibility mutation.' This clearly distinguishes it from sibling tools like handover.requests with action=delete.

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 explicitly states the alternative: 'Prefer handover.requests with action=delete for new integrations,' and the 'Legacy Reporter compatibility' wording implies this is only for legacy flows. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructive behavior, but the description adds meaningful specifics: unpublishing, trashing, and removal of the 'stable public projection'. It could further clarify reversibility or permissions, but it provides valuable context beyond the annotation.

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

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

Two sentences, front-loaded with the primary action, and no wasted words. The second sentence efficiently adds context and guidance, earning its place.

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

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

For a single-parameter mutation tool with no output schema, the description provides sufficient context: purpose, legacy status, effects, and guidance for new integrations. It is complete enough for an agent to select and invoke the tool 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?

The schema already fully documents the 'slug' parameter with a 100% description coverage. The description adds little about the parameter itself beyond repeating that it targets 'one report', so it does not exceed the schema-driven baseline.

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

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

The description clearly states the tool's action: 'unpublishes and trashes one report' and identifies it as a 'Legacy Reporter compatibility mutation'. It distinguishes itself from siblings by noting its legacy scope and contrasting it with 'explicit Handover lifecycle controls'.

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 explicitly guides usage: 'prefer explicit Handover lifecycle controls in new integrations' implies this tool is only for legacy compatibility, steering users toward alternatives for new work. This is a clear when-to-use vs. when-not-to-use statement.

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

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

Beyond the destructiveHint annotation, the description discloses permanence ('permanently deletes'), the preconditions ('empty product Space', 'delete its maintained files and requests deliberately first'), and the legacy-only nature. This adds meaningful behavioral context beyond annotations.

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

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

Three sentences deliver purpose, prerequisite, and alternative without any redundancy or fluff. 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?

Given the tool's simplicity (one parameter, no output schema) and strong annotations, the description covers purpose, usage, legacy status, and prerequisites. Minor gaps like exact error handling are not critical for this 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 already fully describes the slug parameter with 100% coverage, so the baseline is 3. The description reinforces that the Space must be empty but does not add new parameter-level syntax or format details.

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 identifies the tool as a legacy compatibility mutation that permanently deletes an empty product Space, using a specific verb and resource. It also explicitly differentiates from newer alternatives like handover.spaces and from sibling deletion tools.

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

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

The description provides explicit usage context: it is for legacy Reporter compatibility, advises deleting maintained files/requests first, and directs new integrations to use handover.spaces with action=delete. This is clear when-to-use and when-not-to-use guidance.

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

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

The annotations already flag destructiveHint=true and readOnly=false, so the safety profile is known. The description adds the non-obvious side effect that the deletion also removes 'its active projection,' which is valuable beyond the annotations. It also hints at legacy-specific behavior ('Legacy Reporter compatibility'), but does not go into permissions or reversibility.

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 two sentences that front-load the core purpose and then give practical alternative guidance. Every word earns its place; there is no redundancy with the schema or annotations.

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

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

Given that this is a destructive tool with clear annotations (destructiveHint=true, idempotentHint=false) and a fully described schema, the description covers the essential behavior: what is deleted (file/asset plus active projection), the legacy context, and the recommended alternative. For a delete operation, this is 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?

Both parameters (slug and path) are fully described in the input schema with 100% coverage, so the description does not need to repeat them. The description's phrase 'maintained product file or asset' loosely maps to the path parameter but adds no technical detail beyond the schema. 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 it 'deletes one maintained product file or asset and its active projection,' giving a specific verb and resource. It also distinguishes itself by labeling the tool as a 'Legacy Reporter compatibility mutation' and pointing to an 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?

Explicitly says 'Prefer handover.resources with action=delete for new integrations,' which tells the agent when not to use this tool and directs to a modern alternative. This is clear guidance for when to use it (only for legacy compatibility) versus when to avoid it.

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 indicate readOnly=false, destructive=false, so the agent knows it is a non-destructive write. The description adds 'backed by an immutable Handover and stable report URL', which is useful context, but does not explain side effects, permissions, or repeated-deploy 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 sentences, front-loaded with the core publish operation and key properties, then clear usage guidance. Every word earns its place with no redundancy.

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?

While the schema is rich, there is no output schema and the description does not mention return values, error behavior, or what the deploy action actually changes. The legacy/alternative note helps, but for an 8-parameter write tool the behavioral and output story is 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?

Schema coverage is 100%, so the input schema fully documents all 8 parameters. The description adds no parameter-specific details beyond what the schema already provides, making the baseline 3 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 identifies the tool as a 'Legacy Reporter compatibility publish operation' with the verb 'publish' and the resource 'Reporter context'. It also distinguishes itself from siblings by recommending handover.create and handover.publish for new integrations.

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 explicitly states 'Prefer handover.create followed by handover.publish for new integrations', making it unambiguous that deploy_context is only for legacy compatibility. This is direct when-to-use vs alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the 'Legacy' context and 'compatibility alias' role, which explains why it exists and hints at potential deprecation. This is useful context beyond annotations, though it doesn't describe any limitations or return behavior.

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

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

The description is two sentences, front-loaded with the tool's purpose and legacy status, and wastes no words. The preference note is concise and actionable.

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

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

For a low-complexity export tool with two parameters and strong annotations, the description covers the essential purpose and usage. It doesn't explain return format, but given the simple 'export' semantics and clear alias nature, this is acceptable. The mention of 'Legacy' and 'prefer handover.okf.export' completes the context for decision-making.

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

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

Schema description coverage is 100%, so both parameters (slug and revision_id) are already documented in the schema. The description adds no parameter-specific context; the baseline of 3 applies because the schema does the heavy lifting for parameter meaning.

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 it's a 'Legacy Reporter compatibility alias' that 'exports a published report as Open Knowledge Format', specifying both the action (export) and resource (published report). It also distinguishes itself from siblings by naming handover.okf.export as the preferred alternative, so no 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 explicitly says 'Prefer handover.okf.export for new integrations', providing a clear when-not-to-use directive. This gives the agent a direct alternative and prevents use of a legacy tool unless necessary for compatibility.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds the 'Legacy Reporter compatibility' context and the single-product-Space scope, providing some additional behavioral framing, but not extensive details like output format or rate limits. This is consistent with annotations and adds modest value.

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 two sentences long, front-loading the core purpose immediately and then providing a sibling alternative. Every word earns its place; no redundant or vague filler.

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

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

For a simple search tool with three fully-documented parameters and comprehensive annotations, the description provides sufficient context: it states the legacy nature, the scope (one product Space), and the preferred alternative. Without an output schema, the description doesn't need to explain return values since this is a straightforward list-returning search tool.

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

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

Schema description coverage is 100% with detailed descriptions for slug, limit, and query. The description does not add new parameter-level semantics beyond what the schema already provides, except implicitly linking slug to 'one product Space'. Baseline 3 is appropriate when the schema fully describes the parameters.

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 performs a 'search for assets in one product Space' and labels it as 'Legacy Reporter compatibility', which specifically identifies both the action and scope. This distinguishes it from sibling tools like handover.search and handover.resources by framing it for legacy use.

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 explicitly advises 'Prefer handover.resources with action=list for new integrations', telling the agent when to avoid this tool and naming the exact alternative. This is clear, actionable usage guidance with an explicit exclusion for new integrations.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds that this is a compatibility alias and clarifies the scope ('published report and its files'), giving context beyond annotations. While it doesn't mention auth or rate limits, the safety profile is well covered and the legacy status is useful behavioral context.

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 two sentences, front-loaded with purpose and followed by actionable guidance. Every sentence is necessary and there is no redundant information.

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

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

For a simple read-only tool with one parameter and no output schema, the description provides sufficient context: purpose, legacy status, and preferred alternatives. It does not describe the response format, but that is a minor gap given the tool's simplicity and strong annotations.

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

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

Schema description coverage is 100%, with 'slug' fully described as 'Stable published report slug from list_contexts.' The tool description itself adds no parameter-specific detail, but the schema carries the semantics, so the baseline of 3 applies.

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 is a 'Legacy Reporter compatibility alias for inspecting a published report and its files,' which identifies the action (inspecting), resource (published report and files), and its legacy nature. It distinguishes from siblings by explicitly recommending handover.publication or handover.get as better alternatives.

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

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

The description provides explicit usage guidance: it is for legacy compatibility only, and 'Prefer handover.publication or handover.get for new integrations' directly tells the agent when not to use it and names the preferred tools. This fully addresses the when-to-use vs alternatives question.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is well-covered. The description adds meaningful context by labeling it a 'Legacy Reporter compatibility read' and specifying that it 'scores the completeness and integrity,' which clarifies the tool's behavioral scope beyond 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 two sentences long, front-loaded with the core action and resource, and includes an explicit alternative without any filler. 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?

The tool has a simple interface (one parameter) and strong annotations, so the description need not over-explain. It clearly states the tool's purpose and provides usage guidance, though it omits details about the exact return format of the health score. Given the low complexity and legacy status, this is a minor gap.

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

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

The schema already provides 100% coverage for the single 'slug' parameter, including its meaning ('Stable published report slug from list_contexts.'). The description does not add parameter-level detail, but with full schema coverage, the baseline of 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 uses a specific verb ('scores') and resource ('one published report'), clearly identifying this as a read operation for context health. It also distinguishes itself from siblings by explicitly recommending handover.get for new integrations, making the tool's niche clear.

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

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

The description explicitly states 'Prefer handover.get plus explicit workflow validation for new integrations,' which tells the agent when to use this tool (legacy Reporter compatibility) and when not to (new integrations). This is direct, actionable guidance with a named alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the tool reads 'immutable revisions' of a single published report and is for legacy compatibility, which provides behavioral context beyond annotations. It does not disclose auth needs or edge cases, but for a read-only operation this is adequate.

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 only two sentences with no filler. The first sentence states the core purpose and scope, and the second provides migration guidance. Every word earns its place, 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?

This is a simple read tool with one parameter, strong annotations, and no output schema. The description covers purpose and usage guidelines, while the schema documents the parameter. It does not explicitly describe the response format, but the title ('history') and the word 'revisions' give sufficient context. Minor gap in not detailing return structure, so not a 5.

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

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

The input schema fully describes the only parameter 'slug' with a clear description, achieving 100% schema_description_coverage. The tool description does not add any additional parameter meaning beyond what the schema already provides, so the baseline score of 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 it is a 'Legacy Reporter compatibility read' for 'immutable revisions of one published report,' with a specific verb (read) and resource. It also explicitly distinguishes itself from handover.get by saying 'Prefer handover.get for new integrations,' making the purpose unambiguous and differentiating it from siblings.

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

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

The description provides explicit when-to-use guidance via 'Legacy Reporter compatibility' and when-not-to-use guidance by directing new integrations to handover.get. This clearly states the appropriate context and 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 readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds useful context about it being a legacy compatibility read, which helps the agent understand its status and potential quirks. It doesn't add details about auth, rate limits, or return format, but the bar is lower due to strong annotations.

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

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

Two short sentences that front-load the primary purpose and include a clear alternative. Every word earns its place with no redundancy or filler.

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

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

For a simple read-only tool with one parameter, strong annotations, and no output schema, the description is fully sufficient. It explains the scope, legacy status, and preferred alternative, making it complete 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?

Schema coverage is 100%, and the slug parameter in the schema already explains it as a 'Stable published report slug from list_contexts.' The tool description doesn't add any extra meaning beyond what the schema provides, so 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 a specific verb and resource: 'inspecting the files and purposes of one published report.' It also distinguishes from siblings by labeling itself as 'Legacy Reporter compatibility' and directing users to 'handover.get' for new integrations.

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?

Explicitly says when to use this tool (legacy compatibility) and what to prefer instead ('Prefer handover.get for new integrations'). This provides clear when/when-not guidance relative to 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?

The description adds the legacy compatibility context, which is not in annotations. It confirms the read-only nature by using 'read,' aligning with readOnlyHint and idempotentHint. It doesn't introduce any contradictions.

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

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

Two sentences: the first states purpose and scope, the second offers alternatives. No wasted words, front-loaded with key information.

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

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

For a simple read tool with one parameter, the description covers purpose, usage guidance, and alternative tools. However, it doesn't specify the return value content beyond 'maintained files,' which could be more explicit, but annotations and schema cover safety and parameter semantics.

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

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

Schema coverage is 100%, with slug described as 'Product Space slug returned by list_products.' The description adds no additional parameter information, but the schema is sufficient, so a baseline score of 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 it performs a 'read' for a 'product Space and its maintained files,' specifying the exact resource and action. It also distinguishes itself from siblings by calling itself 'Legacy Reporter compatibility' and pointing to preferred alternatives.

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

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

It explicitly says to prefer handover.spaces and handover.resources for new integrations, giving clear guidance on when not to use this tool. This differentiates it from the handover.* siblings and sets a 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 already declare read-only, idempotent, and non-destructive behavior. The description adds value by labeling it a 'Legacy Reporter compatibility read,' which explains its purpose and suggests it's a fallback rather than a first-choice tool. No contradictions.

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 concise sentences cover purpose, scope, and usage guidance with zero wasted words. Front-loaded with the essential 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?

For a simple read tool with one parameter and strong annotations, the description is mostly complete. It explains the purpose and points to the preferred alternative. However, it does not describe the return value or format of the 'score' for product knowledge completeness, which is a minor gap given no output schema.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter 'slug' as a Product Space slug returned by list_products. The description does not add extra semantic detail beyond what the schema provides, so baseline 3 applies.

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 it's a 'Legacy Reporter compatibility read' that scores product knowledge completeness, using a specific verb and resource. It also distinguishes itself from the preferred alternative by directing new integrations to handover.spaces with action=health.

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

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

Explicit guidance is provided: 'Prefer handover.spaces with action=health for new integrations.' This tells the agent when not to use this tool and names the alternative, making usage clear.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a contextual detail ('Legacy Reporter compatibility') and the scope ('across product files'), but no additional behavioral traits like rate limits or pagination. With strong annotations, the description adds moderate value beyond 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?

The description is two sentences, front-loaded with purpose, and includes the usage guidance in the second. Every word earns its place, with no redundancy or filler.

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

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

For a simple read-only tool with one parameter and no output schema, the description is complete. It states what the tool does, identifies the alternative, and implies the return type (version history). The annotations cover safety and idempotency, making the context fully adequate.

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

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

The input schema fully describes the only parameter (slug) as 'Product Space slug returned by list_products', so schema coverage is 100%. The description does not add any additional meaning about parameters, so it relies on the schema. 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: reading version history across product files. It also explicitly distinguishes itself from the preferred alternative, handover.resources with action=get, noting its legacy 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 provides explicit usage guidance: 'Prefer handover.resources with action=get for new integrations' tells the agent when NOT to use this tool and what to use instead. It also labels the tool as 'Legacy Reporter compatibility', indicating it is only for legacy use cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds context about it being a 'Legacy Reporter compatibility read' and the scope 'maintained product files and assets', but does not disclose additional behavioral traits like pagination or return format. This is similar to the mid-tier example, so a 3 is appropriate.

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 concise sentences, front-loaded with the purpose and followed by an alternative recommendation. No wasted words, clear structure.

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 description is complete enough for a simple read-only list tool with good annotations. It states the legacy context, what it lists, and the preferred alternative. However, it leaves a slight ambiguity about what 'maintained' means and does not explicitly mention return format, so it is a 4 rather than 5.

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

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

Schema coverage is 100%, and the schema already describes the 'slug' parameter as 'Product Space slug returned by list_products.' The description does not add any parameter-level detail beyond this, so the 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: a read-only operation that lists maintained product files and assets. It uses the specific verb 'lists' and identifies the resource, distinguishing it from sibling tools by labeling it as 'Legacy Reporter compatibility'.

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 explicitly says to prefer handover.resources with action=list for new integrations, providing a clear alternative and when/why to use this tool. This gives direct usage guidance and distinguishes it from better-suited 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?

The description adds behavioral context beyond annotations by stating the comment is 'durable' and the revision is 'immutable', implying persistence and anchoring stability. It also instructs to preserve exact quote and context. Annotations are all false and do not contradict the description.

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

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

Two sentences, front-loaded with the action, and no wasted words. It states the action and the key prerequisite in a compact format.

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 tool has a complex nested target object, but the description gives essential guidance (read first, exact quote). It does not cover return values or error cases, but with no output schema and high schema coverage, that is not a significant gap.

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

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

Schema coverage is 100%, but the description adds valuable meaning by saying to 'preserve the exact quote and surrounding context', which directly informs how to populate the target.selector fields. This goes beyond the schema's basic 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 uses a specific verb ('Add') and resource ('durable comment anchored to selected text or lines in an immutable artifact revision'). It clearly distinguishes from siblings like handover.comment by emphasizing the anchored/selected-text nature.

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 instruction 'Read the artifact first' provides a clear prerequisite and context for use. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of a 5.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds useful context about what is read (revision-anchored metadata, authorship, resolution) and the semantics of the 'status=open' filter. No contradictions with annotations.

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

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

The description is two sentences long, front-loaded with the core action and resource, and includes a practical tip. Every sentence earns its place with no redundancy or fluff.

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 (4 parameters, no output schema) and strong annotations, the description adequately covers purpose and provides a key usage scenario. It could mention more about what the response contains, but since no output schema exists, the description's current level is sufficient.

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

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

Schema coverage is only 25% (only handoverId has a description). The description compensates by explaining the use of 'status=open' and mentioning 'revision-anchored' which clarifies the revisionId parameter. 'File comments' and 'selected text' hint at the artifactId's role, adding meaningful parameter semantics.

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

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

The description uses a specific verb ('Read') and clearly defines the resource: 'revision-anchored file comments, selected text, status, authorship, and resolution metadata.' This distinguishes it from sibling tools like handover.read_artifact (likely reads artifact content) and handover.thread (likely reads thread context).

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 a concrete usage example: 'Use status=open to find feedback that still needs action.' This gives clear context for when to use the tool, but it does not explicitly mention alternative tools or when not to use it, stopping short of a 5.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds transparency by stating that the action replaces assignments and affects only collaboration state, not the revision itself. This helps the agent understand the scope of side effects, which is valuable beyond the annotations.

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

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

Two concise sentences, with the key action and object placed first. Every word adds value: the first sentence states the operation, the second clarifies the non-destructive scope. No filler or repetition.

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 only two parameters and no output schema, the description fully captures the purpose, behavior, and scope. It answers the likely questions: what does it change, and what does it not change. No additional context is needed given the simplicity and the rich schema.

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

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

The input schema already has 100% description coverage: 'handoverId' and 'principalIds' are clearly explained with patterns and constraints. The description reinforces the replacement semantics but does not add new details about parameters beyond what the schema provides. 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 uses the specific verb 'Replace' and clearly identifies the resource: 'the open assignments' with 'supplied collaborator identities.' It also establishes what the tool does NOT do ('not the immutable handover revision'), making its scope unambiguous and distinguishing it from other handover-related tools.

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

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

The description conveys the tool's effect and implies its use case: to set or update handover owners. It does not explicitly name alternative tools or exclusion criteria, but the distinction between the mutable collaboration state and the immutable revision provides practical guidance. A clear 'when to use' statement with sibling comparisons would elevate it to a 5.

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

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

Annotations already indicate readOnlyHint=false, which aligns with the 'Append' action. The description adds the behavioral detail that it can optionally notify mentioned collaborators, which is not captured by annotations. However, it doesn't disclose other aspects like permission requirements, whether comments are immediately visible, or rate limits.

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

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

The description is a single concise sentence that front-loads the core action ('Append a discussion comment') and includes the optional mention behavior. There is no wasted text or redundancy.

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 simplicity of the tool, the description, schema (100% coverage), and annotations provide adequate context. It states the primary action and the optional side effect. However, it does not describe the return value or success behavior, and there's no mention of whether the comment requires publication to appear.

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

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

Schema description coverage is 100%, with each parameter (handoverId, body, mentionPrincipalIds) having a meaningful description. The tool description itself adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 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 uses a specific verb 'Append' and identifies the resource as 'a discussion comment', which clearly distinguishes it from sibling tools like handover.update_comment (edit) and handover.annotate (annotate). It also mentions the optional notification behavior, making the purpose precise.

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 that handover.update_comment should be used for editing existing comments or that handover.thread retrieves the discussion. There are no explicit exclusions or contextual cues beyond the inherent meaning of 'append'.

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

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

Annotations only indicate non-read-only and non-idempotent, which is thin. The description adds crucial behavioral details: revisions are immutable, expectedRevisionId prevents overwriting, and artifact semantics are inherited/replaced. This goes well beyond what annotations provide.

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

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

Three focused sentences with no filler. The first sentence gives the core action, the second explains the critical guard, and the third clarifies artifact inheritance.

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

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

For a 5-param mutating tool with nested objects, the description covers the essential semantics: append, concurrency, artifact behavior. The schema handles parameter details, and no output schema exists, so return values aren't required. This is sufficient for correct selection and invocation.

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

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

Schema covers all parameters, so baseline 3. The description adds rationale for expectedRevisionId and explains artifact merging behavior, which enriches the schema's technical 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 (append), the resource (immutable revision to a handover), and the required prerequisite (reading the current snapshot). It distinguishes itself from sibling tools like handover.create by emphasizing continuation and concurrency protection.

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 explicitly instructs that the tool is used after reading the current snapshot, and explains the purpose of expectedRevisionId as a lock against lost updates. While it doesn't name alternative tools, the workflow is clear enough for an agent to choose it appropriately.

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

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

The annotations are all false, providing little positive safety info. The description adds useful behavioral context: the initial revision is immutable, and authorship comes from the authenticated Handover identity, which is not captured in annotations. It does not mention failure modes, but covers key behavioral traits beyond the schema.

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

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

The description is two dense sentences, front-loaded with the action. Every word contributes meaning; no redundancy or filler.

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

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

The schema is complex with nested objects and anyOf conditions, but the description is brief. It does not mention the return value (no output schema), the requirement to provide note/brief/artifacts, or how this tool relates to other handover operations. While adequate, it leaves gaps in an otherwise complex tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters in detail. The tool description does not add extra parameter guidance, so the baseline score of 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 action (Create) and resource (durable shared context), and adds the distinctive 'initial immutable revision' aspect, which differentiates it from sibling tools like handover.continue or handover.publish.

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 you should use this tool to create a new handover context, but it does not explicitly say when to use it versus alternatives such as handover.continue or handover.publish. It also lacks exclusion criteria or alternative recommendations.

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 discloses that HTTP secrets are referenced by runtime variable name and never supplied as tool input, adding important authentication context beyond the annotations, which only indicate it's a write operation (readOnlyHint=false) but not destructive.

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

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

One sentence of 15 words, immediately front-loading the purpose; no filler or redundancy.

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 complex 9-parameter create tool, the description is minimal but the schema covers all parameter details; the lack of output schema is not a concern for a create operation, but the description could mention provider-specific prerequisites beyond what the schema already states.

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?

All 9 parameters have schema descriptions (100% coverage), so the baseline is 3; the description's mention of secrets is redundant with the secretEnv parameter description, adding no new parameter semantics.

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

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

The description clearly states the action (create) and the resource (destination), specifying the two types (GitHub or signed HTTP), which distinguishes it from sibling handover.source.create for sources.

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 guidance on when to use this tool or how it differs from alternatives; the description does not mention handover.export or source.create as alternatives, leaving the agent to infer from 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?

The description adds valuable context beyond annotations: the export is queued (asynchronous), one-way, and provider delivery does not mutate the Handover revision. It also clarifies the idempotent nature of the export despite idempotentHint=false on the tool call, adding nuance rather than contradicting.

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 two sentences, front-loaded with the action and key constraints, and contains no redundant wording. It is highly efficient.

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 description covers the core behavior, immutability, and non-mutating delivery, which is sufficient for an export queue operation. It does not specify the response format or how to track the queued job, but siblings like handover.exports cover listing, making it adequately 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 input schema already describes all three parameters (handoverId, revisionId, destinationId) with clear meaning. The description does not add additional parameter-level details, so baseline 3 applies due to 100% schema coverage.

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

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

The description uses a specific verb 'Queue' and clearly identifies the resource ('immutable revision') and target ('configured destination'). It distinguishes this export tool from siblings like handover.publish or export_okf by focusing on exporting an immutable revision to a pre-configured destination.

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 when to use this tool (to queue an export of a revision) but does not explicitly state exclusions or alternatives. It provides clear context without contrasting with sibling export tools (e.g., handover.okf.export).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds useful context about what is inspected (destinations and delivery history) but does not disclose return format, pagination, or other behavioral details. With annotations covering the safe read nature, a 3 is appropriate.

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, well-structured sentence that front-loads the verb and resource. Every word adds value, with no filler or repetition.

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 tool is simple (one parameter, no output schema) and the description adequately conveys what the tool does and what it returns conceptually. It would be slightly improved by noting whether destinations and history come in a single response or separate, but given the available structured information, it is nearly 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 input schema fully documents the only parameter handoverId with a description and pattern, achieving 100% schema_description_coverage. The tool description does not add additional meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description uses the specific verb 'List' with a clear resource ('provider-neutral export destinations and durable delivery history') scoped to a handover. This clearly distinguishes it from sibling export tools like handover.export and handover.destination.create.

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 clearly frames the tool as an inspection/listing operation for a handover's export destinations and delivery history, which implies read-only usage. However, it does not explicitly mention when not to use it or point to alternatives, so it falls short of a 5.

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

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

Annotations only indicate destructiveHint=true and readOnlyHint=false; the description adds no additional behavioral context such as which actions are destructive, permissions needed, or side effects. For a CRUD tool with multiple actions, this is a significant gap.

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, concise sentence that efficiently communicates the core actions. It is front-loaded and avoids redundancy or filler.

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

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

This is a complex multi-action tool with 8 parameters and no output schema. A single generic line is insufficient to cover action-specific requirements, return behavior, or edge cases like the legacy ACL fields that produce migration errors. The description lacks essential contextual detail.

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

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

The schema description covers 100% of parameters, so the baseline is 3. The description's phrase 'change handover membership' adds implicit meaning for 'add' and 'remove' actions, but it does not elaborate on parameter specifics beyond what the schema already provides.

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

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

The description lists specific operations ('List, inspect, create, update, delete, and change handover membership') on a clear resource ('organizational folders'), making the purpose evident. It does not explicitly distinguish from the sibling tool 'manage_folders', which may have overlapping scope, so it loses a point.

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 use this tool versus alternatives like 'manage_folders' or other handover.* tools. It merely enumerates actions without specifying context, prerequisites, or exclusions, leaving the agent without clear decision support.

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 safety profile is covered. The description adds value by specifying exactly what data is read (snapshot, continuation brief, artifact metadata, revision history), which is meaningful behavioral context beyond the annotations.

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

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

The description is a single, focused sentence that front-loads the core action ('Read a handover snapshot...') and provides a necessary usage hint. Every word earns its place, with no fluff or repetition.

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 only two parameters and no output schema, the description is quite complete by listing the four returned components (snapshot, continuation brief, artifact metadata, revision history). It could be improved by explaining what a 'continuation brief' is, but for a simple get operation this is sufficient.

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

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

Schema coverage is 100%, with both parameters having clear descriptions. The description's instruction to omit revisionId for the current snapshot largely repeats the schema's 'omit to inspect the current revision.' Thus, the description adds minimal semantic value beyond the schema.

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

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

The description uses a specific verb 'Read' and lists concrete resources: snapshot, continuation brief, artifact metadata, and revision history. This clearly distinguishes it from sibling tools like handover.search (searching) and handover.read_artifact (reading a specific artifact).

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

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

The description implies the tool is for inspecting handover details but does not explicitly contrast with alternatives like handover.search or handover.read_artifact. It gives a practical tip about omitting revisionId, which helps with parameter usage but not 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is fully covered. The description adds useful behavioral context: the access requirement (Owner) and the 'durable' provenance aspect. This adds value beyond annotations without contradicting 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?

Two sentences, zero waste. The description front-loads the core function ('List organization import sources') then adds the access note and provenance qualifier. Every word earns its place.

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

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

For a zero-parameter, read-only, list-style tool with strong annotations, the description is largely complete. It states the purpose, the access requirement, and the nature of what's returned. It could slightly improve by clarifying what 'durable provider provenance' concretely returns (e.g., records, metadata shape), but given no output schema and the simple nature of the tool, this is adequate.

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

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

The tool has 0 parameters, so the parameter_semantics dimension defaults to a baseline of 4 per the rubric. The description meaningfully describes what is returned (import sources and provenance), which gives the answer shape even without parameters. There's nothing a parameter description could add since there are no params.

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 ('organization import sources and durable provider provenance'). It distinguishes from siblings by focusing on import sources/provenance, which differs from handover.export/handover.exports (exports) and handover.okf.import (import action). The 'durable provider provenance' phrasing is somewhat jargon-heavy but conveys the scope.

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 notes 'Owner access is required', which communicates an access prerequisite. However, it does not explain when to use this tool vs alternatives like handover.okf.import or import_okf (which act on imports) or handover.exports (which lists exports). No explicit when/when-not guidance or named alternatives is 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 declare readOnlyHint=true and idempotentHint=true, so the description needs less safety disclosure. It adds minimal behavioral context about the output format and recipient but does not contradict annotations. No mention of side effects or return behavior, but annotations cover the critical operational safety.

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 efficiently communicates the verb, resource, and output format. No extra words or redundant details are present.

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 low complexity and rich annotations, the description is mostly complete. The main gap is that with no output schema, it doesn't clarify what the returned bundle looks like or how it is delivered to the caller, though the name 'OKF bundle' gives a basic indication.

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

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

Schema coverage is 100% with both parameters (`handoverId` and `revisionId`) having descriptions, including the default behavior for `revisionId`. The tool description adds no additional parameter-level information, so the baseline of 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 exports a handover revision as an Open Knowledge Format bundle, giving a specific verb and resource. However, it does not differentiate from the sibling `handover.export`, so it misses the higher distinction bar.

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 given on when to use this tool versus alternatives like `handover.export` or `export_okf`. The description only indicates the action and recipient, lacking any contextual comparison or exclusion.

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 claims 'Replaying the same bundle is idempotent,' but the annotations declare idempotentHint=false. This is a direct contradiction. No additional behavioral context about permissions, error handling, or side effects is provided.

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 concise sentences with no unnecessary words. Information is front-loaded and easy to parse.

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?

Although the schema is complete, the tool is a mutation with no output schema and the description omits usage guidance, potential errors, and conflict-handling behavior. The idempotency contradiction further reduces completeness and trustworthiness.

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 provides 100% coverage with detailed parameter descriptions, so the baseline is 3. The description adds minimal value beyond schema, only linking handoverId to the concept of an immutable revision.

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 (Import), the resource (Open Knowledge Format files), and the destination (a new immutable Handover revision). It distinguishes from sibling tools like export_okf and handover.okf.export by focusing on import into Handover.

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 such as import_okf or handover.okf.export. The description lacks any context about prerequisites, exclusions, or typical 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 and idempotentHint, so the safety profile is covered. The description adds value by listing the specific publication attributes returned (stable report URL, entry file, access mode, selected revision), which goes beyond what annotations convey. No contradiction 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, front-loaded sentence that uses the active verb 'Read' and enumerates concrete items. There is no filler or redundancy; every word contributes 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?

Despite having no output schema, the description enumerates the return values. Annotations cover operational safety, and the schema covers parameter requirements. For a simple read tool, this is complete and self-contained.

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

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

Schema description coverage is 100% for both parameters, so the schema fully explains slug and handoverId. The description does not add further parameter-level meaning beyond what the schema already states, so a baseline score of 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 uses the specific verb 'Read' and explicitly names the resource ('publication') and the data items (stable report URL, entry file, access mode, selected revision). This clearly distinguishes it from sibling tools like handover.get (general handover info) or handover.publish (creating a publication).

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 clear context by stating what the tool reads, making it obvious it is for inspecting publication details. However, it does not explicitly name alternatives or exclusion criteria, so it falls short of a 5. The context is sufficient for an agent to infer when to use it.

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 indicate readOnlyHint=false and destructiveHint=false, so the description adds only modest behavioral context: 'Create or update' signals upsert semantics, and 'stable /r/{slug}/' suggests a persistent URL. However, it does not disclose details like authorization requirements, side effects on existing content, or behavior when called repeatedly, beyond what annotations imply.

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, well-structured sentence that leads with the primary action and resource. It is concise with no filler or repetition, effectively conveying the tool's essence without wasting 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?

Given the tool complexity (6 parameters, 2 with enums) and the absence of an output schema, the description provides the core business context but relies heavily on the schema to fill in parameter interactions. It explains the purpose and URL structure sufficiently, and the schema covers parameter semantics, so no critical gaps exist for a tool of this scope. A slightly richer description (e.g., typical use case) would earn a 5.

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

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

The input schema has 100% coverage with descriptive parameter explanations (e.g., slug, revisionMode, access). The description adds the URL pattern /r/{slug}/ which complements the slug parameter, but overall it does not materially add meaning beyond the schema. It meets the baseline for high schema coverage without going further.

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: 'Create or update a stable /r/{slug}/ report projection of a Handover revision.' It identifies the resource (Handover revision), the output (stable report projection), and the URL format. This distinguishes it from sibling tools like handover.export or handover.publication by focusing on creating/updating a persistent report view.

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 implicitly conveys that this tool is for publishing a handover as a report but provides no explicit when-to-use or when-not-to-use guidance, nor does it name alternatives. For example, it does not compare this to handover.export or other publication-related tools. The usage context is inferred rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful output details (paths, hashes, media types, UTF-8/base64 content), but it does not disclose behavior such as what happens with binary files when includeBinary is false, or any limits. It is consistent with annotations, but not rich in behavioral context.

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 one concise sentence that front-loads the primary action and return content. Every word adds value, and there is no fluff or repetition of schema details. It is appropriately sized for the tool's simplicity.

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, strong annotations, and full schema coverage, the description is largely complete. It explains return contents but does not explicitly state that omitting files returns all files or that binary content requires includeBinary=true; however, the schema provides these details. Sibling tools that might overlap are not addressed, so slightly incomplete for full 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?

Schema description coverage is 100%, with detailed descriptions for slug, files, and includeBinary. The description adds little beyond the schema, merely mentioning 'selected files' and 'UTF-8 or base64' which already appear in the schema. Baseline 3 is appropriate because the schema carries the semantic load.

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 returns selected files from a published report, including paths, hashes, media types, and content. It uses a specific verb (return) and resource (published report). However, it does not explicitly distinguish itself from sibling tools like handover.get or handover.read_artifact, so it lacks direct sibling differentiation.

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 explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or alternative tools. The usage context is only implied by the verb 'pull' and the resource 'published report', so an agent has no clear decision boundary.

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 provide read-only, idempotent, non-destructive hints. The description adds valuable behavioral context: UTF-8 vs base64 encoding and explicit truncation reporting, going beyond what annotations and schema convey.

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

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

Two concise sentences, front-loaded with purpose and immediately useful output details. No filler or redundancy.

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

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

For a simple read operation with robust annotations and complete schema, the description adequately covers output formats and truncation behavior. It lacks an output schema but partially compensates by describing returns, making it nearly 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?

Schema coverage is 100%, and both parameters are well-documented. The description adds minimal parameter-specific meaning; 'bounded' and 'truncated' indirectly reference maxBytes but do not elaborate on artifactId usage.

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 (read) and resource (bounded artifact content) with specific output details. It distinguishes itself from siblings like handover.get by focusing on content reading, though it does not explicitly name alternatives.

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

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

It gives clear sequencing guidance ('after inspecting a handover') and explains how text/binary content is handled. No explicit exclusions or alternative tool references, but the context is sufficient for basic use.

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 indicate readOnlyHint=false and destructiveHint=true. The description lists delete, which aligns with destructiveHint, but adds no extra behavioral context such as irreversibility, permission requirements, or operation-specific effects. It does not go beyond what annotations and schema already convey.

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

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

The description is a single sentence of 11 words, listing all four operations and the resource. It is front-loaded with action verbs and contains zero waste.

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 CRUD tool with 9 parameters, the description is minimal. The schema provides complete parameter semantics, but the description does not clarify operation-specific parameter requirements (e.g., id needed for update/delete) or explain return behavior. Annotations cover safety traits, making it adequate but with clear 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 100%, with every parameter having a description. The tool description itself adds no parameter detail beyond naming the operations, so the baseline of 3 applies because the schema does the heavy lifting.

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

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

The description uses specific verbs (list, create, update, delete) with a clear resource (work requests) and scope (in a Space). It distinguishes this tool from siblings like handover.spaces or handover.resources by focusing on work requests as a distinct entity.

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

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

Usage is implied by the title 'Manage space requests' and the action enum, but there is no explicit guidance on when to use this tool versus alternative tools like handover.create or handover.annotate. No exclusions or alternatives are mentioned.

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 aligns with the annotations (destructiveHint=true) by explicitly including 'delete', and readOnlyHint=false allows for write operations. However, it adds little beyond the annotations, such as what specifically gets destroyed or whether versioning is protected or immutable.

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 11-word sentence that is front-loaded with verbs and contains no filler. Every word contributes to conveying the tool's scope and actions.

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

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

This is a complex tool with 13 parameters, 5 actions, no output schema, and a destructive annotation, yet the description is only a high-level summary. It does not explain how actions map to parameters, what 'version' means, or when to use specific actions, leaving significant gaps for an agent to infer.

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 100% schema description coverage, all 13 parameters already have clear descriptions in the schema. The tool description merely repeats the action names (list, create, delete) that appear in the action enum, so it adds no additional parameter meaning beyond the schema.

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

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

The description clearly names multiple specific actions (list, inspect, create, version, delete) and the resource type (maintained knowledge and assets in a Space). It is specific enough to understand what the tool does, but does not explicitly distinguish it from sibling handover tools like handover.create or handover.get.

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 offers no guidance on when to use this tool versus alternatives. It is a single sentence listing operations, with no mention of prerequisites, exclusions, or preferred scenarios, so an agent gets no help choosing between this and the many sibling 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=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile for a search/read operation. The description adds the retrieval-mode behavior (hybrid/semantic/lexical across metadata and artifact content) which is useful. No mention of result ordering, pagination behavior, or status filtering, but with strong annotations the burden is lower. Description aligns with annotations; no contradiction.

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

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

Two sentences, both substantive. The first defines scope, the second gives a concrete usage tip. No filler or redundancy. Front-loaded with the core purpose. Could arguably mention pagination or result format but remains efficient.

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 search tool with no output schema and 5 parameters at 0% schema coverage, the description provides the core purpose and one usage pattern but doesn't explain cursor-based pagination, status semantics, or result ordering/format. A read-only search tool with idempotent hints is relatively low-risk, so the gaps are moderate rather than severe. Adequate but with room to explain parameter behavior.

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 parameter meaning. The description explains mode behavior somewhat ('hybrid, semantic, or lexical retrieval') and implies query usage via the empty-query note, but doesn't explain what 'active/archived/trashed' status means, how limit behaves, or what cursor pagination returns. The enum values for mode are inherently self-explanatory, partially compensating. Marginal value added beyond the schema; 3 is baseline despite low coverage.

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?

Description states a specific verb ('find') and resource ('current shared context') with clear scope: retrieval across metadata and artifact content, supporting hybrid/semantic/lexical modes. It distinguishes itself somewhat from handover.get (which fetches a specific handover) but doesn't explicitly name the alternative. The 'empty query to list recent handovers' clarifies a key behavior.

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 clarifies that an empty query lists recent handovers, giving concrete guidance on a common usage pattern. It implies when to use search (when you need to find/relevance-rank context) vs get (exact ID), but doesn't explicitly state when NOT to use it or name sibling alternatives. Reasonable context provided, no exclusions.

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

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

The description adds context about owner-managed operation and secret handling, which goes beyond the annotations. However, it does not disclose side effects, return values, or what happens post-creation. Annotations already cover readOnly/destructive hints, so this is acceptable but not rich.

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 concise sentences that front-load the core purpose and add one critical constraint. No filler, and every phrase earns its place.

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

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

With 8 parameters and no output schema, the description is relatively sparse. It covers the two provider types and the secret rule, but omits anything about the result of a successful creation or post-creation behavior. The rich schema compensates partially, though a bit more context would be helpful.

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

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

Schema description coverage is 100%, and each parameter has a descriptive explanation. The tool description itself does not add meaning beyond the schema, except reinforcing the secretEnv note which the schema already includes. This matches the baseline for fully covered schemas.

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?

Description clearly states 'Create an owner-managed GitHub folder or signed HTTP source', which specifies a verb (create), a resource (import source), and the two supported types. This distinguishes it from siblings like handover.source.run and handover.destination.create.

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 a clear operational constraint: 'Secret values remain deployment configuration and are never tool input.' This is a strong when-not guideline. However, it does not explicitly name alternatives or when to choose this over other create tools, so it stops short of a 5.

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

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

Annotations already declare non-read-only and idempotent; the description adds useful context by stating that repeating the same commit returns the existing durable job, which explains the long-running job behavior. No contradiction with annotations.

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

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

Exactly two sentences, front-loaded with the primary action, and no fluff or redundant wording. Every word earns its place.

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

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

For a single-parameter tool with thorough annotations (idempotentHint, openWorldHint) and no output schema, the description sufficiently explains the behavior and the durable job outcome. The schema provides the needed parameter context, making this adequately 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 schema fully covers the sole parameter sourceId with a description and pattern, so the description doesn't need to add parameter-specific details. It adds no extra parameter meaning beyond the schema, but the 100% coverage supports the 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?

Clearly states it imports a GitHub source, with 'pin and import the current GitHub version' conveying the action and resource. This distinguishes it from siblings like handover.source.create, which likely creates source definitions rather than running imports.

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 context that it imports the current GitHub version and notes idempotent retry behavior, but doesn't explicitly state when to use this over alternatives like handover.pull or handover.source.create. Usage is implied, not explicitly differentiated.

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 no behavioral context beyond the annotations. Annotations already indicate destructiveHint=true, and the description merely lists actions including 'delete' and 'archive' without explaining consequences such as irreversibility, permission requirements, or side effects. It does not contradict annotations, but it also does not enhance the agent's understanding of the tool's behavior.

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

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

The description is a single, well-structured sentence that front-loads the key actions and resource type. It is concise with no unnecessary words or repetition, 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?

The tool has 8 parameters and 6 distinct actions, but the description does not explain which parameters are needed for each action, nor does it mention return behavior (and there is no output schema). For instance, it does not state that create might require 'name' and 'kind', or what 'health' returns. Given the complexity, the description is too sparse to fully guide invocation.

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

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

Schema description coverage is 100%, and every parameter has a clear description. The tool description does not add parameter-level meaning beyond what the schema already provides. Baseline of 3 is appropriate since the schema carries the full burden of parameter documentation.

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

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

The description clearly states the tool's purpose: 'List, inspect, create, update, archive, or delete logical company areas.' It uses specific verbs and a defined resource ('logical company areas'), which distinguishes it from sibling tools like handover.folders or manage_folders by clarifying that these are company areas, not just generic folders.

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 does not mention exclusions, prerequisites, or scenarios where sibling tools might be more appropriate. For example, no distinction is made between spaces and folders or product-related operations. This leaves the agent 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds contextual value by noting 'without changing revision history,' which clarifies a specific side-effect the tool avoids. However, it does not disclose other behaviors like pagination, error handling, or access requirements, so some transparency gap remains.

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 action ('Read') and lists the objects being read. Every word earns its place, with no redundant fluff. It is appropriately sized for the tool's simplicity.

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?

While there is no output schema, the description clearly enumerates what will be returned (comments, explicit mentions, assignments, eligible collaborators). Given the low complexity, complete schema, and strong annotations, this is nearly sufficient. However, it lacks details on output structure (e.g., whether it's a list, ordering) and has a slightly ambiguous term 'eligible collaborators,' leaving a small completeness gap.

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

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

The schema provides 100% coverage with a clear description for the single parameter 'handoverId' (including a pattern). The tool description adds no additional parameter meaning, but the schema already fully documents the parameter. Baseline for high schema coverage is 3, and the description does not enhance it further.

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 starts with the verb 'Read' and specifies the exact content: comments, explicit mentions, assignments, and eligible collaborators. This clearly distinguishes it from sibling tools like handover.comment (which likely writes) and handover.get (which may return handover metadata). The qualifier 'without changing revision history' reinforces its read-only nature.

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 its usage by stating what it reads, but it does not explicitly say when to use this over alternatives such as handover.get or handover.search. There is no mention of exclusions or prerequisites, so the usage context is implied rather than clearly guided.

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

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

Annotations already convey readOnly=false and destructiveHint=false. The description adds meaningful context beyond annotations by mentioning the two actions (edit vs resolve/reopen) and the resolvedRevisionId condition, which clarifies the effect of the operation without contradicting the annotations.

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

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

The description is two sentences, front-loaded with the primary purpose, and the second sentence adds a targeted usage hint. No extra words or redundant 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?

The tool is moderately complex with 7 parameters, but the schema provides comprehensive detail. The description covers the core scenarios (edit and resolve/reopen) and the resolvedRevisionId behavior, which is sufficient given the rich schema. It does not mention all parameters, but they are well-documented in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only repeats the resolvedRevisionId guidance already present in the schema, providing no additional parameter meaning beyond what the schema already documents.

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

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

The description uses specific verbs ('Edit', 'resolve/reopen') and clearly names the resource ('authored comment', 'annotation'), distinguishing it from siblings like handover.comment and handover.annotate. It also mentions the condition for setting resolvedRevisionId, providing a clear scope.

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 clear context for when to use the tool: editing an authored comment or resolving/reopening an annotation. It does not explicitly name sibling alternatives or exclusions, but the restriction to 'authored' comments and the specific actions imply appropriate usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing what the tool exposes (auth details, tenancy info) and explaining that it confirms attribution and tenancy, going beyond the hint annotations. It doesn't describe auth failure behavior, but for a whoami read tool that's acceptable.

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

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

Two sentences, zero filler. The first sentence enumerates the exact returned data, the second gives the actionable use case. Every word earns its place with no redundancy.

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, no-output-schema read tool with strong annotations (readOnly, idempotent, non-destructive), this description is complete. It fully covers what the tool returns and when to call it. There's nothing meaningful missing for an agent to confidently select and 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?

Tool has 0 parameters, meeting the baseline of 4 for zero-parameter tools. There's no parameter burden to carry, and the description fully explains what the returned data represents, so no compensation for unknown params is needed.

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?

Description uses a specific verb ('Return') with clear resource scope: 'authenticated person or service agent, organization, workspace, role, and granted scopes.' The tool name 'handover.whoami' is distinctive and unrelated to any sibling, and the description clearly establishes it as an identity/auth verification tool, separating it from the surrounding data-management 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?

Description gives explicit when-to-use guidance: 'Call this before reading or publishing to confirm attribution and tenancy.' This provides clear actionable direction for the agent on when this tool should be invoked in a workflow, which is strong contextual framing.

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 are all false, providing no safety or idempotency hints. The description adds a behavioral trait by calling itself a 'compatibility alias,' which hints at wrapping behavior. However, it does not disclose potential side effects like replacing files or revision conflicts, leaving the agent to infer those from the schema parameters. This is adequate but not rich.

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 two sentences, front-loaded with the core purpose and then the guidance to prefer a sibling. Every word earns its place, with no fluff or redundancy.

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 description and rich schema together provide a complete picture for a legacy compatibility tool. It names the purpose, the legacy status, and the alternative. The only minor gap is not explicitly explaining the 'Reporter context' vs 'published report' terminology, but this is not critical given the schema's clarity.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no parameter-level detail beyond what the schema provides. Baseline 3 applies because the schema carries the burden.

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 it 'imports Open Knowledge Format files into a published report' and identifies itself as a 'Legacy Reporter compatibility alias.' This specific verb+resource pairing distinguishes it from the sibling handover.okf.import, which is explicitly noted as the preferred alternative for new integrations.

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 explicitly sets usage context: 'Legacy Reporter compatibility alias' signals it is for existing Reporter integrations, and 'Prefer handover.okf.import for new integrations' provides a clear alternative. This tells the agent exactly when to use this tool and when not to.

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 tool read-only, idempotent, and non-destructive, so the bar is lower. The description adds the context that this is a legacy compatibility read, but it does not disclose additional behavioral traits such as response format, pagination, or authorization behavior beyond what annotations and schema cover.

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 two concise sentences with no filler. It front-loads the core purpose and follows up with a critical usage recommendation, earning every word.

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?

Despite no output schema, the tool is a simple filtered list with strong annotations and clear parameter definitions. The description provides purpose and usage guidance, making it complete for this level of complexity.

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

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

Schema description coverage is 100%, with both status and product_slug fully described in the input schema. The description adds no parameter-specific meaning, so the baseline of 3 applies.

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 identifies the tool as a legacy read operation for product requests, using a specific verb ('read') and resource ('product requests'), and it distinguishes itself from siblings by explicitly naming handover.requests as the preferred alternative. The title 'List backlog' reinforces the action.

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

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

The description explicitly tells users to prefer handover.requests with action=list for new integrations, which serves as a clear alternative and exclusion. It implies this tool is only for legacy Reporter compatibility, giving concrete guidance on when to use it.

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 and idempotentHint, so the safety profile is covered. The description adds meaningful context beyond annotations by revealing the tool is a legacy alias and that it lists published reports, which helps set expectations about its role in the API surface.

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. It states the purpose, adds legacy context, and gives an explicit alternative without any 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 read-only listing tool with fully documented parameters and no output schema, the description is complete enough. It covers what the tool lists, its legacy status, and the preferred alternative, leaving no critical gaps for an agent to select and 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 100%, so all five parameters are already documented in the schema. The description does not add parameter-level details, so the baseline of 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 lists published Handover reports and identifies itself as a legacy compatibility alias. It explicitly distinguishes itself from handover.search, making the purpose 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?

It explicitly says 'Prefer handover.search for new integrations,' giving clear guidance on when not to use this tool and naming the preferred alternative. The legacy compatibility framing implies usage only for existing Reporter integrations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about legacy compatibility and the preferred alternative, but doesn't detail return format or filtering behavior beyond the schema. It provides some context but not rich behavioral disclosure.

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 two concise sentences with no wasted words. It front-loads the purpose and immediately provides usage guidance, making it highly efficient.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers essential aspects: purpose, legacy status, and an explicit alternative. It doesn't explicitly say 'lists products' but the tool name/title make that clear. It is sufficiently complete for the tool's simplicity.

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

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

The input schema description covers 100% of the single parameter, so the baseline is 3. The description does not add any additional meaning about the 'search' parameter beyond what the schema already provides, making it neutral.

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 as a 'Legacy Reporter compatibility read for product Spaces', indicating a read operation for product spaces. It distinguishes itself from the preferred alternative, handover.spaces, by explicitly naming it.

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 explicit guidance: 'Prefer handover.spaces with action=list for new integrations,' which tells the agent when not to use this tool and what to use instead. This is clear and actionable.

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 context that these actions are mapped to Handover organizational folders, implying the operations affect Handover resources rather than the original Reporter folders. Combined with the destructiveHint annotation, the agent knows it's a destructive operation, but the description does not elaborate on specific side effects or permissions. No contradiction with annotations.

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

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

The description is two sentences, front-loading the core concept of legacy compatibility and providing a clear preferred alternative. No unnecessary 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?

The description provides essential high-level context—that this is a legacy compatibility layer and that handover.folders is preferred—which is critical for an agent deciding between siblings. The rich schema covers parameter details, and the destructive annotation covers safety, so the description need not explain those. However, it could still mention that some legacy fields are unsupported, but that's in the schema already.

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?

All parameters have descriptions in the schema (100% coverage), so the schema already explains their semantics. The description adds no parameter-specific information, so it relies on schema coverage. 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 identifies the tool as 'Legacy Reporter compatibility folder actions mapped to Handover organizational folders,' which clarifies its general role but does not enumerate the specific operations (list, create, update, delete, etc.) visible in the schema. The title 'Manage Reporter folders' is generic, and the description does not distinguish the tool from handover.folders beyond the legacy compatibility note.

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 explicitly states 'Prefer handover.folders for new integrations,' providing clear guidance on when to use this tool vs. the alternative. It also indicates this is for legacy compatibility, so agents understand the intended use case. This is exactly the kind of when-to-use guidance expected.

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 discloses the core mutation (moving to in_progress), the dry_run preview capability, and its legacy status. Annotations already indicate a non-read-only, non-destructive mutation, so the description adds useful context beyond annotations. It does not describe side effects beyond the status change, but the key behaviors are covered.

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

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

Two sentences, zero filler. The first sentence states the purpose and mutation; the second provides usage guidance and an alternative. Every word contributes, with no repetition of schema or annotations.

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

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

Given the tool's moderate complexity (3 parameters, no output schema), the description covers purpose, usage, and key behaviors. It lacks explicit return-value details for the non-dry-run case, but the tool is a mutation and the description is otherwise thorough. The 'legacy compatibility' context and alternative guidance round out the usage picture.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value for the dry_run parameter by explaining its intended purpose: 'inspect the exact batch before changing it'. This goes beyond the schema's 'return the selected requests without changing their status' by framing it as a safety/preview mechanism.

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 function: it 'previews or moves open requests to in_progress' as a 'Legacy Reporter compatibility mutation'. This distinguishes it from siblings by framing it as a legacy-compatible alternative to handover.requests.

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

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

Explicit guidance is provided: 'Use dry_run=true to inspect the exact batch before changing it' and 'prefer handover.requests for new integrations'. This tells the agent when to use the tool and when to use an alternative, satisfying the when/when-not requirement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds 'legacy compatibility alias' and 'safe local materialization,' which provide context about the tool's nature and use case beyond the annotations. No contradiction is present.

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 two short sentences, immediately states the core function, and includes the recommended alternative without any wasted words. It is well-structured and front-loaded.

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

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

For a simple read-only tool with full parameter documentation and annotations, the description is largely sufficient. It covers purpose, legacy status, and an alternative. However, with no output schema, it does not detail the return format, though 'returning report files' gives a basic idea. This slight gap prevents a perfect score.

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

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

Schema description coverage is 100%, so the schema already documents all parameters with clear descriptions. The tool description does not add parameter-specific meaning beyond the schema, so the baseline score of 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 a specific action ('returning report files') and resource ('Reporter context'), and explicitly distinguishes itself from handover.pull by labeling itself as a legacy compatibility alias. This leaves no ambiguity about what the tool does.

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 explicit usage guidance with 'Prefer handover.pull for new integrations,' directly telling the agent when to use this tool versus an alternative. It also implies legacy-only usage, which is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safely. The description adds 'current bytes' and 'maintained' but provides limited behavioral context beyond that (no auth requirements, edge cases, or return format). It does not contradict annotations but also does not go much beyond 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?

Two succinct sentences: the first states the purpose, the second directs to the preferred alternative. Every word earns its place, and critical information is front-loaded.

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

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

For a simple read tool with full schema coverage and complete annotations, the description is nearly adequate. It could improve by noting that no output schema exists and what format 'current bytes' implies, but the guidance to prefer handover.resources and the schema references make it sufficiently 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?

Schema description coverage is 100%, with parameters 'slug' and 'path' each having source references (list_products and get_product/get_product_index). The description adds no additional parameter meaning, so the baseline of 3 applies when the schema fully documents parameters.

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 ('read') and resource ('product file or asset'), and clarifies it is a 'Legacy Reporter compatibility' operation. This distinguishes it from sibling tools like handover.resources, and the term 'current bytes' specifies the exact data being 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?

Explicitly states it is for legacy Reporter compatibility and 'Prefer handover.resources for new integrations,' giving clear when-to-use and when-not-to-use guidance. This directly differentiates it from the modern alternative.

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 are neutral (all false), so the description carries the burden. It discloses two key behaviors: this is a 'full-file republish' (not a partial update) and it 'appends an immutable Handover revision' (each call adds a new revision). This adds value beyond the schema/annotations, though it could mention more about side effects or prerequisites.

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 two sentences, front-loaded with the core purpose and behavior. The second sentence directly addresses usage alternatives. 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?

Given the tool's complexity (8 params) and lack of output schema, the description covers purpose, usage, and key behavior. It doesn't explain return values or error conditions, but for an update tool with no output schema, this is a minor gap. Overall it is sufficiently complete for an agent to use 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?

The input schema describes all 8 parameters with 100% coverage, so the schema is the primary source. The description adds no parameter-specific information, which is acceptable per the baseline. It doesn't repeat params, so no penalty.

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 a specific action: 'full-file republish' of a Reporter context, and distinguishes it from siblings by labeling it as 'Legacy Reporter compatibility' and explicitly mentioning 'appends an immutable Handover revision.' This goes beyond just saying 'update' and differentiates from handover.continue.

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 explicit guidance on when to use this tool: for legacy Reporter compatibility, and when not: 'Prefer handover.continue for new integrations.' This is a clear directive that helps an agent choose between 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 show readOnlyHint=false, matching the 'mutation' wording, and no contradiction. The description adds context by calling it 'Legacy Reporter compatibility' and specifying it 'creates or versions one maintained product file,' which goes beyond the annotation flags. However, it does not elaborate on side effects, return values, or the meaning of 'maintained,' leaving some behavioral ambiguity.

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 compact, only two sentences, with each sentence carrying essential information: the first defines the purpose, the second provides usage guidance. No redundancy or filler.

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

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

Given that there is no output schema and annotations are minimal, the description effectively conveys the core purpose, legacy status, and preferred alternative. However, it remains vague about versioning behavior (e.g., whether old versions are retained, how versioning is triggered) and does not mention expected return values, leaving some operational details unspecified.

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

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description does not add any additional meaning or clarify parameter relationships beyond what the schema provides, thus the baseline score of 3 applies.

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 and resource: it is a 'mutation that creates or versions one maintained product file.' It also distinguishes itself from siblings by labeling it as 'Legacy Reporter compatibility' and referencing the preferred alternative, handover.resources.

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

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

Explicit guidance is provided: 'Prefer handover.resources with action=create or action=update for new integrations.' This tells the agent when not to use the tool and which alternative to use, satisfying the when/when-not requirement.

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 are all false, so the description carries the burden. It identifies the operation as a mutation and says it 'creates or versions' files, but doesn't disclose specifics like versioning behavior, overwrite semantics, or permission requirements. The minimal added context earns a middle score.

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

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

Two sentences, no filler. The first sentence states purpose and scope, the second gives usage guidance. Content is front-loaded and every word adds value.

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 batch file operation with a rich schema, the description conveys the core action, scope, and legacy context. It doesn't mention return values or error behavior, but there is no output schema and the schema covers the input details. Overall adequate for the tool's role among siblings.

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

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

Schema description coverage is 100%, so the schema fully defines parameters and their meanings. The description adds no parameter-specific details, but the baseline is appropriate given the schema's completeness.

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+resource: 'creates or versions multiple maintained files in one product Space.' It clearly distinguishes itself from siblings by labeling it 'Legacy Reporter compatibility' and pointing to handover.resources for new integrations.

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?

Explicitly says 'Prefer handover.resources for new integrations,' providing a clear alternative and indicating this tool is for legacy scenarios. This gives direct when-to-use guidance beyond just a vague purpose.

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