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

Annotations indicate the tool is not read-only, not open-world, not idempotent, and not destructive. The description adds value by explaining that the comment is attributable and does not modify or approve, which clarifies the mutation's scope. However, it lacks details on whether it always succeeds, errors for invalid versions, or requires special permissions. With annotations covering the basic safety profile, the description provides some additional behavioral context but not comprehensive transparency.

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 with a clarifying follow-up sentence, both concise and front-loaded with the core purpose. It wastes no words and is easy to scan. It could slightly benefit from mentioning parameter parameters, 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?

Given the tool has 9 parameters (4 required), no output schema, and annotations lacking details, the description is insufficient. It does not explain the return value (e.g., feedback ID), behavior on duplicate idempotency_key, or how reply_to_feedback_id works. The context signals of high parameter count and low schema coverage demand a richer description.

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 44% (4 of 9 parameters have descriptions). The description does not mention any parameters, so it adds no value beyond the schema. For the parameters without schema descriptions (x, y, page, label, reply_to_feedback_id), the description provides no guidance. Since coverage is low, a score of 3 is appropriate because the description fails to compensate for undocumented 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 'Add an attributable review comment to a saved project version' with a specific verb and resource. It also distinguishes from sibling tools like 'add_project_pin' and 'approve_version' by explicitly noting it does not modify or approve. However, it does not explicitly differentiate from other feedback-related tools like 'resolve_project_feedback' or 'list_project_feedback'.

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 some context by stating it 'does not modify source or approve the version', which helps the agent understand it is for commenting only. However, there is no explicit guidance on when to use this versus alternatives (e.g., 'add_project_pin' for non-attributable notes or 'resolve_project_feedback' for marking issues), and no mention of prerequisites like requiring a saved project version.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the description adding 'Add' is consistent but adds little. The description does not disclose required permissions, side effects (e.g., does it overwrite or create duplicates?), or behavior with respect to the idempotency_key (which is self-described in schema). The 'safe' qualifier for links is vague. Overall, the description provides minimal behavioral context beyond what annotations already 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 sentence, making it concise and front-loaded with the action. However, it is too brief to cover essential details. While every word serves a purpose, the brevity compromises clarity for a non-trivial tool with nine parameters. A slightly longer description with parameter context would improve it.

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 has 9 parameters, no output schema, and complex behavior (idempotency, positioning, surfaces), the description is far from complete. It neither explains return values nor guides parameter usage. An agent lacks essential context to invoke the tool reliably, especially without output schema to infer results.

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 only 11% schema description coverage, the description should compensate by explaining key parameters. It mentions 'note or safe http(s) link' which covers kind and url, leaving seven other parameters (x, y, label, surface, project_id, version_id, idempotency_key) unexplained. The idempotency_key description exists only in schema, not in the tool description. This is insufficient for an agent to correctly construct calls.

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 adds an 'attributable note or safe http(s) link' to a project workspace. It identifies the key resource (pin) and the two kinds (note, link), which aligns with the 'kind' enum. It is specific enough to distinguish from siblings like 'remove_project_pin' or 'list_project_pins' by stating the action is addition, though it could better clarify what 'attributable' means.

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 siblings or alternatives. It does not mention prerequisites (e.g., need for a valid project_id), conditions for safe use, or when not to use it. The agent receives no help in deciding between this and related tools like 'add_project_feedback' or 'remove_project_pin'.

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 idempotentHint=true and destructiveHint=false. The description confirms idempotency and adds the effect 'make it current', which is a key behavioral trait beyond annotations. However, side effects on the previous current version are not disclosed.

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

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

The description is concise with two short, front-loaded sentences. No word wasted. However, the second sentence could be integrated with the first for even tighter structure. Still, it 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 is a simple mutation with few parameters and annotations covering idempotency and destructiveness, the description is minimally adequate. But it lacks context about what 'request_id' refers to, how to obtain it, and how this tool relates to the approval workflow (e.g., listing requests first). The absence of output schema increases the need for this context.

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

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

Schema description coverage is 0%, so the description must explain the two parameters. It does not mention 'request_id' (the required UUID for the approval request) or the optional 'note'. The agent receives no guidance on what these parameters represent or how to populate them.

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 approves a 'pending immutable artifact version' and 'makes it current', using specific verb and resource. This distinguishes it from sibling 'approve_version' by specifying the artifact type and immutability.

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 version must be pending, but does not explicitly state when to use this tool over sibling 'approve_version' or when not to use it. No alternative tools are mentioned. Usage guidance is minimal and left to inference.

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

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

Annotations already state destructiveHint=true and idempotentHint=true. The description adds valuable context about the authorization model ('separately delegated review authority') and explicitly clarifies side-effect boundaries (no publish, export, permission changes). This goes beyond the annotations by specifying what does NOT happen, which is helpful for an agent assessing risk.

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 redundancy. The first sentence delivers the core action and authorization context; the second sentence clarifies exclusions. Every word earns its place. It is front-loaded and achieves maximum clarity with minimal text.

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

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

For a 4-parameter mutation tool with annotations, the description covers the operation, authorization, and what it does not do. However, it omits any indication of return value or result behavior (e.g., whether it returns the updated version). Given no output schema, a brief note on return could improve completeness. The idempotency hint is present in annotations but not explained in description, which could be relevant for repeated calls.

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 clear descriptions for all four parameters. The description does not significantly add meaning beyond the schema—it mentions 'approve one saved version' but the schema already calls the candidate version 'saved'. The confirmation constant is self-evident. No parameter semantics are enriched beyond what the schema 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 explicitly states the action: 'approve one saved version and make it the project's active version'. It also clarifies what it does not do ('Does not publish, export, or change project permissions'), which distinguishes it from siblings like 'approve_artifact_version' and export/publish tools. The verb 'approve' and resource 'version' are specific and 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 phrase 'Use separately delegated review authority' hints at the prerequisite context, but does not explicitly state when to use or not use this tool. The exclusion list ('Does not publish, export...') implies alternatives exist, but no sibling tools are named. The guidance is implied rather than explicit, leaving room for agent misinterpretation.

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 asynchronous 'queue one durable build' behavior, the returned project_id and job_id, and the need to use get_build for completion status and the protected preview. Since annotations already cover idempotency and non-destructiveness, this adds useful lifecycle context 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?

The description is two concise sentences, front-loaded with the action and followed by the necessary outcome details and follow-up tool reference. Every sentence earns its place with no wasted words.

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

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

For a complex 16-parameter tool with nested objects and no output schema, the description covers the essential lifecycle: creation, queued build, returned IDs, and status retrieval via get_build. The schema is exhaustive and annotations clarify safety behavior, though terms like 'durable build' and 'protected preview' could be explained slightly more.

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 already explains all parameters in detail. The description only adds a general 'structured conversation brief' reference and does not elaborate beyond schema descriptions, meeting the baseline but not exceeding it.

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 ('Create'), identifies the resource ('a new 2ools project'), and adds scope by mentioning the structured conversation brief and queued durable build. It differentiates from siblings by explicitly directing status/preview retrieval to get_build.

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 implies when to use this tool: when you have a structured conversation brief and want to create a project and queue a build. It points to get_build for follow-up but does not explicitly name alternatives like refine_project or list_build_systems.

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 annotations (destructiveHint=true, idempotentHint=true), the description adds meaningful behavioral detail: it 'close[s] its durable run history' and preserves terminal truth for already-terminal runs. This explains the destructive and idempotent nature more concretely, showing what gets closed and what remains unchanged.

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

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

The description is extremely concise: two sentences, with the primary action front-loaded. Every word adds value, covering scope, destination, and edge cases without 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 cancellation tool with no output schema and only four required parameters, this description is fairly complete. It explains what is stopped, what happens to the run history, and which run states are unaffected. It could mention what the caller receives in response, but the absence of an output schema makes that less critical.

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 four parameters are fully documented in the schema with descriptions (100% coverage), so the description does not need to add parameter details. The description itself does not elaborate on parameter semantics, but the schema carries that burden, and a 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 stops a queued or running Agent execution and closes its durable run history. This specific verb-resource pair ('Stop one ... Agent execution') distinguishes it from sibling tools like cancel_build, which targets builds, not agent runs.

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 scopes usage to 'queued or running' runs and notes that completed, failed, stalled, and already-canceled runs are unaffected, providing clear when-to-use guidance. It does not explicitly name alternative tools like cancel_build, but the context makes the intended use case 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description adds important behavioral details: completed versions are not deleted and terminal builds remain unchanged. This clarifies the extent of the destructive action and aligns with the idempotent hint.

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, front-loaded with the primary purpose and followed by essential scope and alternative guidance. Every sentence contributes value 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?

Given the tool's simplicity (one parameter, no output schema) and the presence of annotations, the description is largely complete. It covers the action, scope, non-destructive aspects, and alternative tool. Minor gaps like immediate effects of cancellation are not critical but could add completeness.

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 job_id parameter is fully described in the schema as 'Build job ID returned by build_from_conversation.' The tool description does not add extra parameter semantics beyond what the schema already provides, 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 the tool cancels a queued or running non-Agent 2ools build, using a specific verb and resource. It explicitly distinguishes itself from cancel_agent_run by noting that governed Agent execution should use that 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?

The description provides clear usage context: use for queued or running builds, not for terminal builds, and explicitly points to cancel_agent_run as the alternative for governed Agent execution. This gives both 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 description goes beyond the annotations (readOnlyHint: false, idempotentHint: true, destructiveHint: false) by revealing atomicity, a five-minute renewable lease, and an immutable budget snapshot. These are important behavioral traits that help the agent understand side effects and what to expect.

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 that is front-loaded with 'Atomically claim' and contains no waste or redundant info. Every phrase adds value, 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?

With no output schema, the description should explain return values; it does hint at the lease and budget snapshot, but not their structure. It also omits parameter details and error scenarios, leaving gaps that make it minimally viable but not fully complete for an agent invoking 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?

Schema description coverage is 0%, so the description must compensate for missing parameter explanations. It does not mention idempotency_key or input_refs at all, and assignment_id is only vaguely implied by 'claim one open assignment.' The description fails to provide the necessary 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 'Atomically claim one open assignment and receive a five-minute renewable lease plus an immutable budget snapshot' clearly states the verb (claim), resource (open assignment), and outcome (lease and snapshot). It distinguishes from siblings like create_work_assignment (creation) and heartbeat_work_session (renewal) by focusing on the specific claim 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 implies usage when an assignment needs claiming, but it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or related lifecycle steps. The context is adequate but lacks direct guidance such as 'use when you want to start work' or 'instead of heartbeat.'

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 explicitly mark the tool as readOnlyHint: true, idempotentHint: true, destructiveHint: false, which already declare it as a safe, read-only, idempotent operation. The description does not contradict these and adds useful context: it reports lineage, review state, page diffs, byte sizes, and SHA-256, which helps the agent understand the behavior's scope. However, it does not mention rate limits, pagination, or performance for large comparisons, so it falls short of perfect transparency.

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, dense sentence that front-loads the core purpose ('Compare two saved versions in one project without returning source') and then lists all reported attributes. Every word carries information. No fluff. This is an example of excellent conciseness.

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

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

Given the tool has 3 well-documented parameters, no output schema, and rich annotations (readOnly, idempotent, non-destructive), the description covers what the tool does and what it reports. The agent can infer it returns a comparison summary. However, it could be slightly more complete by hinting at the exact output format (e.g., 'returns a diff object with ...') since there is no output schema. Still, for a comparison tool with good structured data, this is quite 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 has 100% coverage with descriptions for project_id, left_version_id, and right_version_id. The schema already provides UUID format and a note that left is 'Earlier or baseline' and right is 'Later or candidate'. The description adds value by indicating the comparison is within one project and clarifies the output fields. Since all parameters are well-documented in the schema, the description provides a meaningful but not essential supplement, earning a 4.

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

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

The description clearly states the tool compares two saved versions in one project, specifies what it reports (lineage, review state, page additions/removals, byte sizes, SHA-256), and distinguishes itself by noting it does not return source. This is a specific verb+resource and differentiates from sibling tools like approve_version, list_artifacts, etc., though it could be sharper about excluding version export or diff 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 implies this is for comparing saved versions without source, but does not explicitly state when to use this over alternatives like get_version or prepare_version_export. There is no mention of prerequisites (e.g., version IDs must exist), nor is there discussion of when not to use it. With 53 sibling tools including several version-related ones, explicit guidance would improve this dimension.

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 key behavioral traits beyond annotations: the preview is temporary (24-hour expiration), free, authless, and read-only. Annotations already cover idempotency (idempotentHint: true) and non-destructiveness (destructiveHint: false), but the description enriches this with usage constraints. 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 three sentences with no waste. The first sentence states the core purpose, the second adds constraints (temporary, authless, expiration), and the third clarifies the prerequisite. Each 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 description covers the tool's purpose, constraints, and prerequisite, but it omits the return value (likely a URL or identifier). Since there is no output schema, the description should ideally indicate what the agent receives after a successful call. The omission leaves a gap for an agent to understand the full interaction.

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, the baseline is 3. The tool description adds minimal extra meaning beyond the schema—it reinforces that the HTML must be 'complete' and 'already created in this chat,' but does not provide new parameter-specific details. The schema already sufficiently describes each parameter.

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 (turn a standalone HTML document into a preview) and the resource (2ools preview). It distinguishes from siblings by specifying 'already created in this chat' and noting it does not generate the page, making it distinct from render_project_preview or similar 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 explicitly instructs the user to write the HTML first before calling the tool, which is a clear prerequisite. However, it does not mention when not to use this tool or suggest alternatives, leaving some ambiguity for the agent.

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

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

Annotations declare idempotentHint=true, and the description adds meaningful detail that reusing the idempotency key returns the original result, implying a 'create or recover' behavior. This goes beyond the bare annotation and aligns with the idempotency hint, with 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 front-loaded sentences with no filler. The core purpose and idempotency behavior are stated efficiently, 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?

With 5 parameters and no output schema, the description covers the core behavior and idempotency but omits details about the optional 'page' parameter, return format, and error cases. It is sufficient for basic tool selection but not for fully anticipating edge cases.

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

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

Schema description coverage is 0%, so the description must compensate. It adds semantics for access ('public or code-protected') and idempotency_key (recovery behavior), but leaves 'page' unexplained and does not elaborate on project_id/version_id beyond what is obvious. Partial coverage at best.

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 ('Create or recover') and resource ('durable public or code-protected link for one exact saved version'). It clearly differentiates from siblings like get_version_share_link (retrieval) and revoke_version_share_link (revocation), and specifies the exactness of the version.

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: to create or recover a durable link for a specific saved version, with idempotency recovery. It does not explicitly mention alternatives or when-not-to-use, but the context is well-defined.

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 noting the assignment is 'durable' and has 'hard ceilings' on steps/time/spend, implying enforcement. Annotations already indicate idempotency and non-read-only, and there is no contradiction. It could go further by explaining consequences of exceeding ceilings.

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

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

A single sentence with no redundant words, front-loading the verb and key differentiators. 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?

The description provides a high-level purpose but doesn't cover important operational aspects such as idempotency behavior (beyond the annotation), error scenarios, or validation details. Given the absence of an output schema and the tool's complexity (10 parameters), the description is adequate but incomplete.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions acceptance criteria and ceilings (mapping to acceptance_criteria, max_steps, max_minutes, max_spend_cents), but doesn't explain other parameters like idempotency_key, due_at, priority, project_id, title, or brief. This leaves 6 of 10 parameters without semantic clarification.

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), the resource (assignment/project work), and specific characteristics (durable, bounded by ceilings). This distinguishes it from sibling creation tools and from other work assignment actions like claiming or submitting.

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

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

The description implies usage when you want to create a bounded assignment, but it doesn't explicitly state when not to use it or name alternatives among the sibling tools like claim_work_assignment or list_work_assignments. It lacks explicit when/when-not 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 mutability (readOnlyHint=false), idempotency (idempotentHint=true), and non-destructiveness (destructiveHint=false). The description adds the authority requirement, which is a useful behavioral constraint. However, it does not disclose what other state changes occur or side effects (e.g., notifications). The description does not contradict 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 extremely concise: two sentences with no filler. It quickly establishes the core purpose and a key prerequisite. 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?

Given the tool has 4 parameters, no output schema, and performs a state-changing action, the description is too sparse. It does not explain the parameters (beyond decision), the expected return value, or how the idempotency key works. An agent would lack sufficient context to invoke this tool reliably.

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

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

Schema description coverage is 0%, so the description must compensate. It only vaguely references the 'decision' parameter by mentioning 'complete or reopen'. The note, assignment_id, and idempotency_key parameters are completely unexplained. This is insufficient for an agent to use the tool correctly without inferring from names.

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 completes or reopens submitted work, which is a specific verb-resource combination. The title 'Review submitted project work' provides context. However, it does not explicitly differentiate from siblings like 'approve_version' which might be confused for similar functionality on different entities.

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 mentions a prerequisite (delegated work-review authority), which is helpful. But it lacks explicit guidance on when to use this tool versus alternatives (e.g., approve_artifact_version for artifacts, or reject_version). No 'when not to use' or comparison with siblings is provided.

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. The description adds value by specifying that raw prompts, tool arguments, credentials, and source bytes are not returned, and that run traces are 'redacted append-only' with 'immutable revision summaries'. This goes beyond the annotations' safety profile.

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 that efficiently states what the tool does and what it does not return. No extraneous words or filler. Every part 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 read tool with two simple parameters and no output schema, the description covers the key data included and excluded. Minor gaps: it does not explain ordering of run traces or behavior when run_limit is exceeded, but overall it is sufficiently complete for an agent to understand the tool's 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?

Schema description coverage is 100%, so the input schema already documents both parameters. The description does not add any additional meaning or context for the parameters (e.g., how run_limit affects results or the format of agent_id). 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 lists the exact data returned (Limits, trigger, revision summaries, run traces) and explicitly states what is NOT returned. This clearly differentiates from sibling tools like 'list_project_agents' which list agents rather than inspect a single one.

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

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

The description provides no guidance on when to use this tool versus alternatives such as 'list_project_agents' to find an agent ID, or when to avoid it. The usage context is entirely implied by the tool name and siblings, placing the burden on the agent to infer.

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, so the safety profile is clear. The description adds critical behavioral context: the tool is read-only ('Read ... without returning stored bytes'), works with immutable version histories, and explicitly excludes returning file bytes. This aligns perfectly with the annotations and provides the agent with a transparent understanding of boundaries.

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, efficiently packing the core purpose, scope, and key constraint ('without returning stored bytes'). Every phrase earns its place without redundancy or fluff. It is front-loaded and highly scannable for an AI agent.

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 has only 2 required UUID parameters, no output schema, and strong annotations, the description provides complete context. It specifies the exact information returned (version history, provenance, attribution, digests, review states) and the key exclusion (no bytes). An agent can confidently decide when to invoke this tool versus download-oriented or listing tools. No gaps are apparent.

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

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

Schema description coverage is 0%, meaning neither parameter is described in the schema. The description compensates by clarifying that project_id and artifact_id identify the artifact whose metadata is returned. However, it could be more explicit about the roles of each parameter (e.g., 'artifact_id' might be a version ID vs. an artifact identifier). Adding a brief note on expected input format or scope would improve this.

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 identifies the resource as 'one artifact's immutable version history, provenance, attribution, digests, and review states.' It also explicitly states what the tool does NOT do ('without returning stored bytes'), which distinguishes it from download-focused tools like prepare_artifact_download. This provides a complete, unambiguous purpose that stands out among 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 implies appropriate usage scenarios: when metadata about an artifact is needed without downloading its content. It contrasts with tools like prepare_artifact_download (which returns bytes) and list_artifacts (which lists multiple artifacts). However, it does not explicitly exclude usage in cases where the artifact ID is unknown, nor does it suggest alternatives like list_artifacts for discovery. Slight improvement needed for explicit 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, establishing safety. The description adds value by specifying exactly what data is returned (status, progress, errors, etc.) and what is not (generated source code). This goes beyond annotations to set accurate agent expectations.

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 redundancy. The first sentence front-loads the tool's purpose and outputs. The second sentence clarifies an important exclusion. Every phrase earns its place, and the structure is easy to scan.

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

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

For a simple read tool with one well-documented parameter, annotated safety, and no output schema, the description fully covers what the agent needs: what it returns, what it excludes, and how to identify the build (via job_id from build_from_conversation). No gaps remain.

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 parameter description already states 'Build job ID returned by build_from_conversation'. The main description does not add further parameter details (e.g., format, validation). Baseline 3 is appropriate since 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 uses a specific verb ('Get') and clearly identifies the resource ('one build's current status, progress, errors, completed version IDs, and protected preview URLs'). It distinguishes itself from sibling tools like 'build_from_conversation' (creates a build) and 'cancel_build' (cancels a build) by focusing solely on retrieving build details. The explicit exclusion ('Does not return generated source code') further clarifies 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 implies that the 'job_id' parameter is provided by 'build_from_conversation', but it does not explicitly state when to use this tool versus alternatives (e.g., after initiating a build). No direct guidance on prerequisites or comparison with siblings like 'list_build_systems' is given, leaving the agent to infer 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 set readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description need not restate those. The description adds value by disclosing that the tool excludes generated source code (a key behavioral constraint). The performance profile (read-only, safe, idempotent) is well-covered. No contradictions are 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 sentences, front-loading the primary purpose and then clarifying a key exclusion. Every sentence adds distinct value, and there is zero redundancy. The length is appropriate for the tool's complexity (one parameter, no output schema).

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 annotations (readOnlyHint, idempotentHint, openWorldHint=false) and the output schema being absent, the major gap is that the description does not state the return format (e.g., is it JSON, does it include timestamps). This is acceptable because no output schema is declared; a brief hint about the return type or structure would push this to a 5. The description adequately covers purpose, scope, and an exclusion.

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 the sole parameter 'project_id' is fully described in the schema with a UUID format and pattern. The description does not add additional meaning beyond what the schema provides (e.g., how to obtain the ID, or whether it refers to a current or archived project). Per the rubric, baseline 3 is correct when schema coverage is high.

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 'Get' and the specific resource '2ools project', and explicitly lists the four categories of data returned: brief, selected pages, active version, and compact version history. It also distinguishes itself from other 'get_project_*' siblings like get_project_activity or get_project_mission by detailing exactly what it retrieves.

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 this is the tool to use for a comprehensive snapshot of project metadata (brief, pages, version, version history). It does not explicitly state when not to use it or name alternatives, but given the many sibling tools that cover specific slices (get_project_context, get_project_discipline, get_project_mission), the explicit negative statement 'Does not return generated source code' helps agents avoid misusing it for code retrieval. A clear 'when-not' improves 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, destructiveHint=false, so the tool is clearly a safe, idempotent read operation. The description adds valuable context about attribution transparency (agents vs humans), which goes beyond annotations. No contradiction found.

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 action and scope in the first sentence, and adding a critical transparency note in the second. Every sentence adds value with zero 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 complexity (3 params, no output schema, rich sibling set), the description covers the core purpose and behavioral transparency well. It could add info about return format or default ordering to be fully complete, but the provided detail is sufficient for an agent to select this 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 fully documents all three parameters (project_id, limit, cursor). The description adds no additional parameter-level detail beyond what the schema provides. 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 verb 'Read' and the resource 'attributable project timeline', and specifies the scope across multiple activity types (human work, external MCP agents, builds, versions, feedback, workspace pins). This distinguishes it from sibling tools like get_project (general metadata) or list_project_agents (specific subset).

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 notes that 'Actor kind is explicit' and clarifies attribution rules (no false human identity for agents), which helps an agent decide when to use this vs. other timeline or listing tools. However, it does not explicitly state when NOT to use it or provide direct alternatives among siblings.

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 a safe, idempotent read. The description adds meaningful behavioral guarantees: the packet is 'source-free', includes an 'exact frozen Curator snapshot', and explicitly states historical Rulebook text is never guessed after revision changes. This exceeds 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?

Two sentences, front-loaded with the action and purpose, followed by a compact list of returned components. 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 description enumerates the packet's components, covering the return content even without an output schema. The revision-safety note adds important behavioral context. Minor ambiguity around 'source-free' and lack of example usage prevent 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 descriptions for both parameters (project_id and include_governance_text). The description adds no further parameter-level detail, so the schema carries the burden; 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 the tool reads a 'source-free operating packet' before acting and enumerates its contents (active version, exact frozen Curator snapshot, Rulebook context, review attention, artifact index, work queue, and current activity cursor). This is a specific verb+resource with a defined scope, and it inherently distinguishes the tool from narrower siblings like get_project.

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

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

The phrase 'before acting' provides clear timing guidance, and the packet composition implies it is the go-to for pre-action context. However, it does not explicitly name alternatives or exclusion scenarios, 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 already cover read-only and non-destructive behavior. The description adds valuable context beyond annotations, such as the fact that disabled shares return no URL and the notion of 'durable sharing state.' This provides additional behavioral clarity without contradicting any 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 short sentences, front-loaded with the core action and resource. No wasted words; every phrase adds meaning.

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

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

For a simple read-only tool with good annotations and a meaningful sibling set, the description is mostly complete. It covers the main return value (URL) and an edge case (disabled shares). However, the lack of any mention of the 'page' parameter and the absence of an output schema prevent 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 0%, so the description carries the burden of explaining parameters, but it only mentions 'one exact saved version' implicitly mapping to version_id and project_id. The optional 'page' parameter is left completely unexplained, which is a significant gap given the low 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 states a specific action ('Read') on a specific resource ('durable sharing state and current URL for one exact saved version'), making the purpose unmistakable. It also distinguishes itself from sibling tools like create_version_share_link and revoke_version_share_link by focusing on retrieval.

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 use of 'Read' clearly implies this is for retrieving an existing share link rather than creating or revoking one, which is reinforced by sibling tool names. It does not explicitly name alternatives, but the context provides sufficient guidance for an agent to know when to choose this tool.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds valuable context beyond annotations: the lease has immutable step/time/spend ceilings and the renewal does not widen them. It also clarifies the scope to the authenticated worker's active lease, which is useful operational 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 a single, well-structured sentence. It front-loads the primary action and includes the key constraint in a prepositional phrase. There is 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 description fully explains the tool's purpose and key behavioral constraint, which is helpful. However, with no output schema and zero parameter descriptions, the description leaves parameter semantics and expected return behavior unexplained. It is adequate but not complete for a tool with three non-trivial parameters.

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

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

Schema description coverage is 0%, and the description does not explain any of the three parameters. While 'session_id' can be inferred as the lease identifier from context, the meanings of 'used_steps' and 'used_spend_cents' are entirely unexplained. The description adds no parameter-level 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 uses a specific verb ('Renew') with a clear resource ('the authenticated worker's active lease') and adds nuance (immutable ceilings). This distinguishes it from siblings like 'submit_work_session' or 'claim_work_assignment' by focusing on lease renewal.

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 implies when to use the tool: when the worker needs to renew an active lease. It does not explicitly name alternatives or exclusions, but the context is unambiguous given the sibling set. The note about immutable ceilings also sets expectations for what the renewal does not change.

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, so the tool is safe and non-mutating. The description adds key behavioral context: 'Returns project/version identity and attribution, never generated source' — confirming it returns metadata but not the generated content itself. This goes 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?

Two sentences, zero wasted words. Front-loaded with purpose, immediately followed by return constraints. Every sentence adds value and is appropriately sized given the sibling list length and tool complexity.

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

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

For a read-only listing tool with fully defined schema parameters and complete annotations, the description covers the key return semantics (identity/attribution, no source). Without an output schema, mentioning that it never returns generated source is helpful. Minor gap: could hint at ordering or pagination, but not critical given the limit parameter.

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

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

Schema coverage is 100%, and the description does not add meaning beyond the schema fields (limit, status). The baseline of 3 is appropriate since schema already documents parameters clearly. The description could hint at defaults or format, but it does not.

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

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

The description states a specific verb ('List') and resource ('approval requests'), and clarifies it deals with 'exact saved versions waiting for a separately delegated reviewer'. This distinguishes it clearly from siblings like list_artifact_approval_requests and approve_artifact_version.

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

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

The description implies usage for retrieving pending reviews via 'waiting for a separately delegated reviewer', but does not explicitly state when to use this tool versus alternatives like list_artifact_approval_requests or approve_version. It provides helpful context but lacks explicit when-not-to-use or alternative names.

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 idempotentHint=true, readOnlyHint=true, and destructiveHint=false, so the agent knows this is a safe read. The description adds behavioral context by specifying the scoping constraint ('exact artifact versions') and the authority requirement, which are not in annotations. 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: front-loaded with purpose, then constraint. 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?

With no output schema, the description should explain what the tool returns. It does not describe the response format (e.g., list of version IDs, metadata). However, for a simple listing tool with good annotations and two parameters, the description is mostly adequate except for the missing return value explanation.

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

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

Schema description coverage is 0%, so the description must compensate. However, the description only hints at filtering by approval status indirectly ('awaiting or carrying a human review decision') but does not explain the status parameter or project_id parameter. The enum and format in schema help, but the description adds no additional meaning for 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 uses specific verbs ('List') and resources ('artifact versions awaiting or carrying a human review decision'), clearly distinguishing from sibling tools like 'list_approval_requests' (which likely lists all approval requests, not artifact-specific ones) and 'list_artifacts' (which lists artifacts themselves).

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 a usage prerequisite ('Requires separately delegated artifact review authority'), which helps the agent determine if the tool is applicable. However, it does not indicate when to use this tool versus alternatives like 'approve_artifact_version' or 'reject_artifact_version'.

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, so the description is not required to repeat safety traits. It adds value by clarifying that the tool returns only metadata (latest immutable versions) and not the stored bytes, which is a critical behavioral trait not captured by 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 sentence of 13 words, front-loaded with the verb and resource. It contains no filler, directly conveys the essential information, and 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 simple list tool with one parameter and no output schema, the description covers the core action and scope. However, it omits details about pagination, ordering, filtering, or the structure of the returned list (e.g., what fields are included). An agent may need to guess at the output format, which limits completeness.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented parameter. The description does not mention 'project_id' at all, nor explain its role, format, or constraints. The schema provides a UUID pattern, but the description adds no semantic value for the parameter, leaving the agent without guidance on how to specify the project.

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 ('List'), the resource ('durable project artifacts'), and the scope ('each latest immutable version'). It also distinguishes itself from siblings by specifying 'without returning stored bytes', which contrasts with tools like 'get_artifact' or 'prepare_artifact_download' that likely return bytes.

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 on what the tool does and does not return (no bytes), implying when to use it (when you need metadata only). However, it does not explicitly name alternative tools for byte retrieval, leaving the agent to infer from sibling names. Still, the context is sufficient for basic usage decisions.

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 known. The description adds account-scope context ('this paid account may explicitly apply') and clarifies that the output is a list of three system types, which is useful behavioral detail 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?

The description is only two sentences, with the core function stated first (front-loaded) and usage guidance in the second. Every word earns its place; no redundant or repetitive content.

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

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

For a simple, read-only list tool with one optional filter parameter, the description, combined with complete schema and annotations, fully captures the necessary context. It names what is returned, scopes access, and gives usage timing. No critical information is missing.

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

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

Schema description coverage is 100%, so the input schema fully documents the single optional filter parameter. The description does not add any additional meaning about the parameter beyond what the schema already states, so 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 function: 'List the Curators, Rulebooks, and Skills this paid account may explicitly apply.' It uses a specific verb ('List') and resource ('Curators, Rulebooks, and Skills'), and distinguishes itself from sibling tools by positioning it as a precursor to build_from_conversation.

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 before build_from_conversation when the user names a creative system or asks what is available.' This clearly indicates when to use the tool and references a sibling tool as the alternative, meeting the highest standard for usage 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 provide readOnlyHint true, idempotentHint true, and destructiveHint false, so the safety profile is clear. The description adds value by specifying it returns status and summary (not full Limits or run traces), which is helpful 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 two sentences, completely front-loaded with the core action, and every sentence adds distinct value (scope, limitations). No 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?

Given readable annotations, a single simple parameter, and no output schema, the description is nearly complete. It covers purpose, scope, and constraints. An explicit note about the return structure of 'status and summary' would push it to 5, but it is already 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%, so the schema fully documents the project_id parameter with format and pattern. The description adds no additional meaning to the parameter beyond what the schema provides, so 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 lists 'built-in Agents assigned to one readable project' with a specific verb ('List') and resource ('Agents'). It distinguishes from sibling tools like list_artifacts or get_agent by scoping to the authorizing account's agents per project.

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

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

The description implies usage for exploring agent status and summary within a project, and tells what NOT to expect (full Limits or run traces), providing some when-not guidance. It does not explicitly name alternatives (e.g., get_agent for details of a specific agent), but the context is adequate for an agent.

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, so the agent knows this is a safe, read-only, effect-free operation. The description adds that the feedback is 'page-anchored' and 'review feedback' with attribution – context beyond annotations. However, it does not disclose pagination, ordering, or error/edge-case behavior (e.g., what if the project has no versions). Annotations cover the core, 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?

The description is a single concise sentence that packs the key aspects: read-only, scoped to versions, anchored to pages, with explicit attribution. No filler, 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 2-parameter tool with no output schema and full annotation coverage, the description provides sufficient context: the scope (project versions, page-anchored, attribution type). It misses only minor details like return format or whether it includes unresolved by default (the default for include_resolved is already in the schema). Only minor gaps remain, so a 4 fits.

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%, meaning the schema already describes both parameters ('project_id' and 'include_resolved'). The description does not add additional meaning about these parameters beyond what the schema provides. Baseline 3 is correct.

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 ('Read'), identifies the resource ('page-anchored review feedback for versions in a project'), and clarifies the attribution type ('explicit human or external-agent'). This clearly distinguishes it from siblings like add_project_feedback or resolve_project_feedback, which are write/update operations.

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

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

The description implies usage: use when you need to read feedback with explicit attribution. The sibling context includes add_project_feedback, resolve_project_feedback, and many read tools, but the description does not explicitly state when NOT to use this tool or name alternatives. Still, the differentiation is clear enough for an agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds minimal behavioral context beyond the annotation set, only specifying that outputs include 'explicit attribution'.

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

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

The description is a single, front-loaded sentence with no extraneous words. Every part of the sentence serves the purpose.

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 list tool with 1 parameter and rich annotations, the description is adequate but incomplete. It does not mention return format (list of items), pagination, or that it returns all pins for the given project.

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

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

Schema description coverage is 0% and the description does not explain the project_id parameter. The parameter name suggests it identifies the workspace, but no additional semantics or usage hints are provided.

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 identifies the resource as 'shared workspace notes and http(s) links', clarifying what pins contain. This clearly distinguishes the tool from siblings like add_project_pin and remove_project_pin.

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, nor does it mention exclusions or prerequisites. The agent must infer from the name alone.

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 value by stating it returns compact metadata without generated source, which is a behavioral trait not covered by annotations. It also clarifies the scope to owned and shared projects, enhancing transparency. 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?

The description is two sentences, front-loaded with the verb, and contains no filler. Every phrase 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?

Given the tool's simplicity (one optional parameter, no output schema), the description provides sufficient context: scope (owned/shared, authenticated account), recency, and return characteristics (compact metadata without generated source). It could be more detailed about the exact response fields, but it is adequate for an agent to invoke 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 covers 100% of the only parameter (limit) with a full description, default, and constraints. The description adds no additional parameter semantics, so the baseline of 3 applies as 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 clearly states it lists recent 2ools projects accessible by the authenticated account, including owned and shared projects. The verb 'List' and resource are specific, and the mention of 'compact metadata without generated source' distinguishes this list operation from get_project, which retrieves a single project.

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: listing projects the authenticated account can access. It also implies the scope (recent, owned, shared) but does not explicitly exclude alternatives like get_project or list_project_pins. No exclusions are stated, but the purpose is unambiguous enough for typical listing 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?

The annotations already establish that this is a safe, read-only, idempotent operation. The description adds a bit of context by enumerating the kinds of objects returned (durable contracts, bounded attempts, etc.), but it does not explain their semantics or any behavioral quirks like pagination or filtering. Given the strong annotation coverage, 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 a single sentence with no filler, which is efficient. However, the unusual enumeration of item types makes it less immediately understandable than a plain 'List work assignments for a project.' Still, it earns a strong score for brevity.

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

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

For a list tool with no output schema and no parameter descriptions, the description leaves key questions unanswered: What exactly are 'bounded attempts' or 'result references'? Does status filter the list? Is there any pagination? The safe-read annotations cover safety, but the functional behavior remains underdescribed, making this incomplete for a 2-parameter tool.

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

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

The schema has zero description coverage for its two parameters, so the description should compensate. It does not mention the project_id requirement or that status filters results, nor does it clarify the meaning of the status values. The parameter names and enum provide basic clues, but the description fails to add 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 the verb 'List' and specifies the resource as project work assignments, elaborated with a set of item types (contracts, attempts, leases, budgets, result references). While the enumeration is jargon-heavy, it clarifies the tool's scope and distinguishes it from sibling list tools like list_artifacts or list_projects. The title reinforces the meaning, earning a solid but not perfect score.

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

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

There is no explicit guidance on when to choose this tool over alternatives, nor any exclusions or prerequisites. The description only states what the tool lists, leaving the agent to infer its use case from the sibling set. This is a clear gap.

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

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

The description adds value beyond the readOnlyHint annotation by disclosing the 5-minute expiration and the privacy guarantee that stored bytes never enter MCP model output. These are not in the annotations and provide important behavioral context. 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 with no wasted words. The primary purpose is front-loaded in the first sentence, and the secondary behavioral note is in the second. Every sentence adds unique 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?

Given the tool's simplicity (3 UUID params, no output schema, good annotations), the description adequately covers purpose, expiration, and a privacy guarantee. It does not describe the return format (the URL), which could be useful, but overall it is sufficient for an agent to understand 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 input schema has 0% description coverage for its three UUID parameters, and the tool description does not explain any parameter semantics. The parameter names ('project_id', 'artifact_id', 'artifact_version_id') are self-explanatory, but the description could clarify that the version must be immutable (hinted) or how to obtain these IDs. It does not compensate for the missing schema descriptions.

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

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

The description clearly states the tool creates a five-minute download URL for one immutable artifact version. It uses a specific verb ('prepare') and resource ('artifact download'), and distinguishes itself from siblings like 'prepare_artifact_upload' (upload direction) and 'get_artifact' (likely metadata retrieval).

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 use when an artifact version needs to be downloaded via a temporary URL, but it does not provide explicit guidance on when to avoid this tool (e.g., if the agent needs the artifact content directly in the model output) or mention alternative tools like 'get_artifact' for metadata. Usage context is clear but not contrasted with siblings.

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

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

Annotations indicate mutation (readOnlyHint=false) and non-destructive intent. The description adds behavioral details: URL expiry, exact bytes requirement, and the review lifecycle, which go beyond annotations. 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?

Two sentences pack key purpose and behavioral constraints without extraneous detail. 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?

Despite 10 parameters, no output schema, and complex behavioral context (review, URL expiry), the description omits what the tool returns, how to use the URL, parameter interactions, and error conditions. It is incomplete for an agent to correctly invoke the 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 only 20% (2 of 10 parameters have descriptions). The description contributes no parameter-level meaning, leaving 8 undocumented parameters. With such low coverage, the description must compensate but fails to do so.

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 five-minute PUT URL for exact bytes, distinguishing it from sibling prepare_artifact_download. The verb 'create' and resource 'PUT URL' are specific, and the mention of external-agent review adds 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 explicitly notes that external-agent output always enters pending review and does not replace the current version before approval, providing clear context for when this tool is used. However, it does not explicitly state when not to use it or mention alternatives beyond 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 indicate readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds valuable behavioral context: the download URL expires in five minutes and the source is delivered via an external download route, not embedded in MCP model output. This goes beyond what annotations provide, though it could mention specific authentication or rate-limit implications.

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

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

The description is extremely concise: two sentences with no filler. The first sentence states the core action and result, the second adds a crucial behavioral note. Every word earns its place, and the most important 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?

Given the low complexity (two UUID parameters) and the absence of an output schema, the description partially covers what is returned (a five-minute download URL). However, it does not explicitly specify the output format (e.g., JSON with a 'url' field) or mention error conditions, prerequisites, or what happens on failure. It is adequate but leaves some ambiguity for an agent needing to handle the result.

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

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

Schema description coverage is 0%, so the description bears full responsibility for clarifying parameters. It mentions 'exact saved version' (implying version_id) and implicitly requires project_id for context, but it does not explain the meaning of either parameter, their expected format beyond UUID, or how they affect the export. The description adds minimal semantic value over the raw 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 states the tool's purpose: 'Create a five-minute download URL for an exact saved version.' It uses a specific verb-resource pair and distinguishes from siblings like 'prepare_artifact_download' (for individual artifacts) and 'create_version_share_link' (likely for persistent sharing). The additional note about source delivery reinforces the tool's unique value.

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 does not explicitly state when to use this tool versus alternatives or mention prerequisites. It implies usage for exporting a complete version via a temporary URL, but no 'when not to' or comparison with sibling tools like 'create_version_share_link' or 'prepare_artifact_download' is provided. The guidance is implicit rather than explicit.

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

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

Annotations already indicate idempotent, non-destructive, and open-world behavior. The description adds valuable context: 'consumes one persisted project iteration', 'preserves the base source as currentCode', and 'returns an asynchronous job_id'. This goes beyond the 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, front-loaded with the core purpose, and no extraneous words. Every sentence contributes essential information about the action, constraints, and return type.

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 explains the key outcome (protected child version, job_id) and an important constraint (consumes iteration). However, it does not cover how to poll the async job, error conditions, or the effect of the 'model' parameter beyond the schema. Still, for a tool with well-documented schema and annotations, this is largely 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 detailed descriptions for each parameter. The description does not add new semantic meaning beyond what the schema provides, meeting the baseline but not exceeding it.

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 'protected child version' from a 'saved base version' and 'concrete review feedback', with specific verbs and resources. It also distinguishes itself from siblings like 'build_from_conversation' by mentioning persistence of base source and consumption of an iteration.

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 'build_from_conversation' or 'continue_project'. The description does not mention prerequisites, exclusions, or scenarios where this tool is inappropriate, leaving the agent to infer usage context.

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

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

Annotations provide idempotentHint=true, destructiveHint=false, readOnlyHint=false, so the description's statement about idempotency is redundant but consistent. The phrase 'with useful feedback' adds context about the note parameter's purpose. No contradictions. However, the description does not elaborate on what the feedback implies (e.g., whether it notifies a creator) or the state change beyond rejection. Given annotation coverage, this is 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?

The description is two sentences long, front-loaded with the action and resource. Every word carries meaning—no fluff, no repetition. It efficiently conveys core purpose and a key behavioral trait (idempotency). An excellent example of concise documentation.

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 2 simple parameters, no output schema, and annotations present. The description covers the core action and idempotency but omits details like what constitutes a 'pending' version, how the rejection is processed (e.g., notifications, state changes), and the meaning of return values. While not complex, the description leaves gaps that could confuse an agent about expected outcomes. It is minimally 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 0%, meaning the description provides no direct explanation of parameters. The mention of 'useful feedback' indirectly suggests the note parameter is for feedback. However, the request_id parameter receives no clarification of what it refers to. With no parameter descriptions in the schema and no elaboration in the description, the agent must infer from the tool name alone. This is insufficient for a 2-parameter tool.

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 'Reject' and the resource 'one pending immutable artifact version'. It also notes the idempotency, which further clarifies the behavior. This distinguishes it from siblings like approve_artifact_version and reject_version (which may apply to a different entity). The purpose is specific and 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 mentions 'Repeating the same decision is idempotent', which gives a usage hint but does not explicitly state when to use this tool versus alternatives like reject_version or approve_artifact_version. There is no discussion of prerequisites, context of use, or when not to use it. This is adequate but lacks explicit 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 provide idempotentHint=true and destructiveHint=true. The description adds context about restoring the saved parent if the version was active, and notes the rejected version remains in immutable history. However, it doesn't detail what triggers the idempotent behavior (e.g., re-calling yields same result) or the full extent of destructiveness (e.g., whether linked artifacts are affected).

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. Every sentence adds value. However, it could be slightly more concise by removing 'Use separately delegated review authority to' if the tool name and title already imply authority context.

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 has 4 required params, 100% schema coverage, no output schema, and no nested objects, the description is fairly complete. It covers the action, side effects, and constraints. The only gap is the lack of behavioral detail about idempotency and destroy operation scope beyond the annotation hints.

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 four parameters. The description does not add any meaning beyond the schema (e.g., no hint about the confirmation constant or the content of decision_note). It lists the required fields implicitly but lacks extra guidance.

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 'reject one saved version' using specific verb+resource. It also distinguishes from alternatives like approve_version and reject_artifact_version by mentioning 'delegated review authority' and describing the effect on the active parent.

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 — when you have delegated review authority and want to reject a specific saved version. While it doesn't explicitly state when NOT to use, the sibling tools like approve_version and reject_artifact_version are clearly different. No explicit exclusions are provided.

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 specify idempotentHint=true and destructiveHint=true. The description echoes 'idempotent' but adds no new behavioral context—e.g., what permissions are needed, whether the pin must exist, or what the response looks like. It does not contradict annotations but also does not enrich 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 extremely concise at two sentences and front-loaded with the action. However, it sacrifices necessary parameter context, which could be added in a compact way without bloating the description.

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

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

Given the simple tool (2 required params, no output schema), the description should at least mention the parameter roles and perhaps a prerequisite like listing pins first. Without this, the agent lacks guidance on how to construct a valid call, making the description incomplete for effective use.

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

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

Schema description coverage is 0%—no parameter descriptions exist in the schema or the description. The description does not explain what project_id or pin_id represent, nor how they relate to each other. This is a critical gap for an agent to use the tool correctly, and the description fails to compensate.

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 'Remove' and the resource 'one shared workspace pin'. It is unambiguous and directly relates to the tool name. However, it does not explicitly differentiate from sibling tools like add_project_pin, though the opposite action is obvious.

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 (when you need to remove a pin) but provides no explicit guidance on when not to use or mention of alternatives like add_project_pin or list_project_pins as prerequisites. The agent must infer context from the tool name and siblings.

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. The description adds value beyond annotations by stating the output format ('protected preview and access-checked workspace links') and that source code is not included. 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?

Two sentences with zero waste. First sentence explains the core action, second sentence provides usage context and return value. 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?

Given the rich annotations (readOnlyHint, idempotentHint, etc.), well-documented parameters, and absence of output schema, the description fully covers what is needed: output type ('preview and workspace links'), security context ('protected', 'access-checked'), and that source code is excluded. No 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 coverage is 100% and each parameter has a clear description in the schema. The tool description does not reference parameters or add additional semantics, but the baseline of 3 is appropriate as the schema already does the work.

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 explicitly states the verb ('Render'), the resource ('interactive, read-only card for one saved 2ools version'), and distinguishes from siblings by emphasizing the read-only nature and the specific use case of viewing/sharing results after get_build or get_project.

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 guidance on when to use: 'Use after get_build or get_project when the user wants to see, open, or share the result.' It does not list explicit exclusions or alternatives, but the context is sufficient for an agent to decide correctly.

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 readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the description adds value by specifying 'Owner-only' and the two possible actions (resolve/reopen). However, for a destructive tool, it does not elaborate on consequences (e.g., whether the action is reversible) or what 'destructive' means in this context. 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 a single sentence of 10 words, front-loaded with the key constraint ('Owner-only'). It is concise with no wasted words. However, brevity sacrifices parameter details, which is a trade-off, but conciseness itself is well-executed.

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 3 parameters, no output schema, and no parameter descriptions, the description is too sparse. It does not explain the role of the resolved parameter, what happens after resolution (e.g., state change, visibility), or prerequisite conditions beyond 'Owner-only'. The tool is more complex than the description acknowledges.

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

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

Schema description coverage is 0%, so the description must compensate but fails to explain any of the three parameters. The description only implies feedback_id via 'one saved feedback item', but does not mention project_id or the resolved boolean (which determines resolve vs. reopen). Without parameter info, the agent cannot correctly map inputs to the expected behavior.

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: 'Owner-only review decision that resolves or reopens one saved feedback item.' It uses a specific verb ('resolves/reopens') and resource ('feedback item'), distinguishing it from siblings like add_project_feedback (creates) and list_project_feedback (lists).

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 mentions 'Owner-only', which implies a usage constraint, but it does not explicitly state when to use this tool versus alternatives (e.g., add_project_feedback for creating, list_project_feedback for viewing). No alternatives or exclusions are provided, leaving the agent to infer 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 flag destructive and idempotent behavior. The description adds valuable context by specifying that ALL public and code-protected URLs are disabled for the version, and clarifies the effect of re-publishing a protected link. This goes 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 sentences, front-loaded with the action, and the second sentence adds useful behavioral nuance. No wasted words or redundant 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 core behavior is clear and the annotations cover the destructive/idempotent profile. However, the complete lack of parameter explanations (especially idempotency_key) and no mention of return values or edge cases leaves gaps for an agent fully understanding the tool's invocation 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 0%, so the description must compensate. It only hints at version_id via 'one exact saved version'; project_id and idempotency_key are entirely unexplained. This is a significant gap for correct invocation.

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

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

The description uses a specific verb 'Disable' and clearly identifies the resource: 'every existing public or code-protected URL for one exact saved version.' It directly contrasts with sibling tools like create_version_share_link and get_version_share_link, 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 usage context is implied (use this to revoke all share links for a version), but there is no explicit 'when to use' or 'when not to use' guidance. The note about re-publishing rotating codes hints at an alternative workflow, but it is not stated as a directive 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?

Annotations already provide idempotentHint, openWorldHint, and non-readOnly. The description adds valuable context: server-side enforcement of Limits, project access, account fuse, and online Engine requirement. It does not contradict annotations and enhances understanding of behavioral constraints.

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 fluff. The first sentence states the core action; the second adds critical behavioral context. Efficiently front-loaded and 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 description explains the action and server-side enforcement but omits what the tool returns (e.g., a run object ID). With no output schema, the agent lacks guidance on how to use the result. Given the complexity (5 required params, side effects), this is a notable 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 description coverage is 100%, so baseline is 3. The main description does not add meaning to individual parameters beyond what the schema provides. It implies prerequisites but does not enhance semantic understanding of fields like task, model, or idempotency_key.

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 real execution') and resource ('project-linked Agent'), clearly distinguishing it from sibling tools like get_agent or list_project_agents by stating the agent must be 'already test-ran and armed'.

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 a precondition: the agent must have been test-ran and armed. This guides usage context, but it does not explicitly state when not to use (e.g., if the agent isn't armed) or suggest alternatives like test-run tools. The context is clear but lacks 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 a critical behavioral fact beyond annotations: ending the lease. It also clarifies that the review is a separate step. Annotations already cover idempotency (idempotentHint=true) and non-destructiveness (destructiveHint=false), so the added context of lease termination is valuable. It does not disclose all consequences (e.g., session cannot be resumed), but is decent.

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, front-loaded with the action, and contains no fluff. It is appropriately sized and immediately conveys the tool's function.

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

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

For a 6-parameter tool with no output schema, the description is too sparse. It does not explain the workflow prerequisites (active lease), the meaning of required fields like idempotency_key, or what happens after submission. Sibling tool names provide some context, but the description alone is inadequate for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It only hints at 'typed result references' (output_refs) and indirectly 'result_summary'. It does not explain session_id, idempotency_key, used_steps, or used_spend_cents. The parameter names are somewhat self-evident, but the description does not provide sufficient guidance for an agent to fill them correctly.

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: 'End the authenticated worker's lease and submit typed result references for a separate review decision.' It uses a specific verb ('end', 'submit') and resource ('lease', 'result references'), and it distinguishes from siblings like heartbeat_work_session (which extends the lease) and decide_work_assignment (which makes the review decision).

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 the final step after completing work, contrasting with heartbeat_work_session (lease renewal). However, it does not explicitly state 'use when work is done and ready for review' or name alternatives. The context is clear enough given the sibling tools, but explicit when/when-not guidance is missing.

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. The description adds behavioral context beyond annotations: it specifies the wait behavior (up to 20 seconds), the ordering (oldest-first), and the resync fallback scenario. It does not elaborate on error behavior or rate limits, but given the strong annotation coverage, the additional context is valuable and consistent.

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, each serving a distinct purpose: the first explains the core polling behavior and ordering, the second explains the resync edge case. No redundant or filler language is present, 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?

Given the tool's moderate complexity (4 params, 100% schema coverage, no output schema), the description covers the wait behavior, ordering, and resync condition adequately. It does not explain the return format (e.g., events array, timed_out flag), but the output schema is absent, so the agent would need to infer or rely on documentation elsewhere. Still, the description is sufficient for an agent to decide whether to invoke this 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 baseline is 3. The description does not add parameter-level details beyond the schema (e.g., explaining 'after_cursor' as head_cursor or next_cursor), but it does give important context for the whole parameter set by describing the overall polling flow. This adds some value but does not go 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 clearly defines the tool's purpose: polling for new project events by waiting up to 20 seconds and returning them in chronological order. It specifies the verb 'Wait', the resource 'attributable project events', and key constraints (newer than a cursor, oldest-first ordering), distinguishing it well from its sibling `get_project_activity` which is implied as a non-waiting, direct query tool.

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 on when to use this tool for polling new events and mentions a specific condition ('if resync_required is true, paginate get_project_activity instead of advancing the cursor'). However, it does not explicitly state when NOT to use it or provide a direct comparison to the sibling `get_project_activity` (only implies it through the resync guidance).

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