Handover

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?

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 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 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?

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.