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

Annotations already indicate mutating behavior (readOnlyHint=false). The description adds useful context by clarifying that it doesn't modify source or approve the version, and 'attributable' implies author tracking. Still, it doesn't disclose return behavior or error cases.

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, direct, front-loaded with the main action. 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 9 parameters, no output schema, and sparse annotations, the description leaves major gaps: no return-value description, no mention of optional positioning/reply parameters, and no guidance on idempotency key behavior. It is inadequate for an agent to fully understand invocation side effects.

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 44% for 9 parameters. The description mentions 'comment' but provides no details for project_id, version_id, label, page, or reply_to_feedback_id. Thus it fails to compensate for 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?

Clear verb+resource: 'add an attributable review comment to a saved project version.' The added sentence explicitly differentiates from approval/source modification, distinguishing it from siblings like approve_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?

Provides context that this tool is for review comments and explicitly states what it does not do (modify source or approve the version). However, it does not name alternative tools or provide explicit when-to-use guidance beyond this 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 indicate this is a write operation (readOnlyHint=false), but the description adds little beyond that. Terms like 'attributable' and 'safe' hint at requirements, but there is no disclosure of side effects, permission needs, or the effect of reusing idempotency_key (which the schema partially covers but the description does not).

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 wasted words. It efficiently conveys the core purpose without unnecessary detail.

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 9 parameters and no output schema, this tool is complex, yet the description only gives the basic purpose. It omits required parameters, coordinate semantics, surface options, version_id usage, and return behavior, making it inadequate for an agent to use the tool confidently.

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

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

Schema description coverage is only 11%, so the description must compensate for the 9 parameters. It only indirectly hints at the 'kind' and 'url' parameters via 'note or safe http(s) link', leaving project_id, version_id, x, y, surface, and label unexplained. This is insufficient for proper parameter understanding.

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 ('Add') and the resource ('an attributable note or safe http(s) link to the shared project workspace'). It is immediately distinguishable from siblings like list_project_pins and remove_project_pin, which serve different operations on the same resource.

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 tool is for adding pins, but it does not explicitly state when to use it versus alternatives or mention exclusions. No direct reference to list_project_pins or remove_project_pin is provided, so guidance is only implicit.

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, read-only=false, and non-destructive. The description adds that the version must be pending and that it becomes current. However, it repeats the idempotency hint and does not disclose potential side effects like replacement of the current version or authorization requirements.

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 with key information front-loaded. The second sentence about idempotency is redundant with the idempotentHint annotation, but the overall size is appropriate.

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 and no parameter descriptions, the description leaves gaps about return values, error cases, and prerequisites. It does not explain what response to expect or how this relates to other artifact approval flow steps.

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 mention either parameter. request_id and note are left unexplained; the agent can only infer from names and formats that request_id identifies some request and note is a comment.

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

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

The description clearly identifies the action (approve), the resource (artifact version), and the outcome (make it current). It distinguishes from sibling tools like reject_artifact_version and approve_version by specifying '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 when there is a pending artifact version approval, but it does not explicitly state alternatives or exclusions, such as 'for project versions, use approve_version'. Sibling tools like approve_version and reject_artifact_version create ambiguity that the description does not resolve.

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 (destructive, idempotent, read/write), the description adds important behavioral context: it changes the active version, requires separately delegated review authority, and explicitly lists non-effects (no publish/export/permission changes). This gives the agent a clear safety and side-effect 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 two sentences, front-loaded with the core action, and every phrase adds value. It avoids fluff and is appropriately sized for the tool's complexity.

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

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

The tool has only four well-documented parameters and no output schema, and the description covers purpose, authority, side-effects, and exclusions. This is complete for an agent to select and invoke the tool correctly without further 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 100%, so the input schema already fully documents every parameter (project_id, version_id, confirmation, decision_note). The description adds minimal new parameter-level meaning beyond clarifying that the version must be 'saved' and 'approved', which is largely redundant with the schema. 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 a specific action: 'approve one saved version and make it the project's active version.' It also distinguishes from siblings by noting it does not publish, export, or change permissions, and uses 'delegated review authority' which separates it from artifact approval or rejection 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 gives clear context for use by mentioning 'separately delegated review authority' and specifies what the tool does not do ('Does not publish, export, or change project permissions'), which helps rule out alternative actions. However, it does not explicitly name sibling tools like reject_version or approve_artifact_version as alternatives, so it stops short of full exclusionary 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 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?

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable context beyond annotations: it specifies that source content is not returned and enumerates exactly what metrics are reported (lineage, review state, page additions/removals, byte sizes, SHA-256 per page). This gives a concrete behavioral picture without contradicting the safety 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 deliver the core action, scope, and output details with no filler. The first sentence is immediate about the tool's function, and the second sentence efficiently lists the reported dimensions.

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 comparison tool with all parameters documented and safety covered by annotations, the description sufficiently explains what the tool does and what it reports. The absence of an output schema is mitigated by the explicit list of reported attributes.

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 three parameters have complete descriptions in the schema (100% coverage), including formats and intended roles ('Earlier or baseline version ID', 'Later or candidate version ID'). The description adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

The description uses a specific verb 'Compare' with a clear resource 'two saved versions in one project' and explicitly excludes returning source, distinguishing it from export-like siblings such as prepare_version_export. This makes the tool's primary function unambiguous.

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

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

It sets clear context by stating the comparison happens without returning source, which hints at when to use it versus export tools. It also lists the reported attributes (lineage, review state, page changes) that signal its use case. However, it does not explicitly name alternative tools or exclusion criteria.

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 annotations, the description reveals the preview is temporary (expires after 24h), read-only, free, and authless. It also clarifies that the tool does not generate the page, which is a significant behavioral caveat. This adds substantial 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 three sentences, front-loaded with the main purpose, followed by constraints (temporary, read-only, expiry) and a vital usage note. Every sentence earns its place with no fluff.

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

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

The description covers the tool's core purpose, prerequisite, and lifecycle well. However, it does not specify what the tool returns (e.g., a URL or preview ID), which is important for an agent to use the result. With no output schema, 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 coverage is 100% with detailed parameter descriptions, so baseline is 3. The description adds context that the HTML must be a complete standalone document already created in chat, which reinforces the html parameter. It doesn't add new syntax details but provides usage nuance.

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 converts a complete standalone HTML document into a temporary, read-only preview, and explicitly says it does not generate the page. This specific verb+resource scope distinguishes it from siblings like render_project_preview.

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

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

The description gives a clear prerequisite: the HTML must already exist in the chat, and it must be called after writing the HTML. It also notes the tool is free/authless and expires after 24 hours, providing context. However, it doesn't explicitly an alternative tool or exclusions, just implies them.

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 the idempotentHint annotation by disclosing that the link is 'durable' and that reusing the key yields the original result. It also clarifies 'recover' behavior. No contradiction with annotations; readOnlyHint=false aligns with a write operation.

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

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

The description is two compact sentences, front-loading the purpose and adding the key idempotency nuance. Every word earns its place with no redundancy or filler.

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

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

Given no output schema and no param details, the description should clarify what the tool returns and under what conditions. It explains durability and idempotency but does not state the response format (e.g., a URL) or error scenarios like invalid version IDs. Moderate completeness for a simple tool, but key expectations are 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?

With 0% schema description coverage, the description must explain parameters. It indirectly covers 'access' via 'public or code-protected' and 'idempotency_key' via reusing behavior, but it does not explain 'page', 'project_id', or 'version_id' beyond generic terms. It partially compensates but leaves gaps.

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 identifies the resource ('a durable public or code-protected link for one exact saved version'). It clearly distinguishes from sibling tools like get_version_share_link and revoke_version_share_link by emphasizing creation/recovery and exact version scoping.

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 idempotent usage: 'Reusing the idempotency key returns the original result' guides agents on when to reuse vs. create new. However, it does not explicitly contrast with get_version_share_link or revoke_version_share_link, so alternatives are implied rather than stated.

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

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

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 declare readOnlyHint=false and idempotentHint=true. The description adds that this is a decision action ('complete or reopen') and that feedback should be 'useful,' which aligns with the note parameter. It also reveals an authorization requirement not captured in annotations. There is no contradiction with annotations.

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

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

The description is two sentences, front-loaded with the main action and followed by an important prerequisite. No wasted words; every sentence 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?

The tool has no output schema and only moderate annotations. The description covers the core action but does not mention return values, side effects, or how this differs from closely related siblings. Given the tool's simplicity and idempotentHint, it is adequate but not comprehensive.

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

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

Schema description coverage is 0%, so the description must compensate. It provides partial meaning for 'decision' (complete or reopen) and 'note' (feedback), but does not explain assignment_id or idempotency_key. With 4 parameters and only 2 lightly covered, the description is insufficient to fully clarify parameter semantics.

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

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

The description uses a specific verb+resource construction: 'Complete submitted work or reopen it with useful feedback.' This clearly differentiates the tool from siblings like approve_version/reject_version by focusing on work assignments rather than versions. The title 'Review submitted project work' reinforces the purpose.

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

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

The description states a clear prerequisite: 'Requires separately delegated work-review authority.' This tells the agent when this tool is available, which is useful context. However, it does not explicitly contrast with alternatives like approve_version/reject_version or mention when not to use it, so it lacks 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, openWorldHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: it explicitly states that raw prompts, tool arguments, credentials, and source bytes are not returned, and describes the return as redacted and append-only. This informs the agent about data sensitivity and completeness without contradicting annotations.

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

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

The description is two sentences long, front-loaded with the action and key result, and avoids irrelevant details. Every word contributes to understanding the tool's purpose and limitations, making it highly efficient.

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

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

For a read-only tool with two parameters and no output schema, the description clearly explains what is returned (Limits, trigger, revision summaries, traces) and what is excluded. It lacks a description of the response structure or pagination behavior, but the schema covers the parameters and the sibling tools provide context. Good overall, with room to explicitly reference list_project_agents for alternative use.

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

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

The input schema covers 100% of parameters with descriptive text for both agent_id and run_limit. The description itself adds no additional parameter-specific guidance beyond the schema; for instance, it mentions 'run traces' but does not elaborate on the run_limit parameter. Thus the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Read' and clearly identifies the resource as 'one Agent's saved Limits, trigger, immutable revision summaries, and redacted append-only run traces'. It distinguishes this from sibling tools like list_project_agents (which lists agents) and run_project_agent (which runs agents), and adds exclusions to avoid ambiguity.

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

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

The description implies when to use this tool by stating it reads a single agent, contrasting with the plural list_project_agents. It also notes that raw prompts and credentials are not returned, which guides against using it when those are needed. However, it does not explicitly name alternatives or provide when-not-to-use scenarios, leaving some room for interpretation.

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 a safe read profile. The description adds behavioral value by mentioning the 'immutable' nature of the history and explicitly stating that stored bytes are not returned, which prevents misuse as a download tool.

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

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

The description is a single sentence, front-loaded with the verb, and contains no redundant information. Every word contributes to the tool's purpose and behavior, 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 must explain return values, and it does by listing the types of information returned (immutable version history, provenance, attribution, digests, review states). It also notes the absence of stored bytes, which completes the data scope. However, it lacks details like pagination or ordering, which is a minor gap for a history endpoint.

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 clarify how project_id and artifact_id relate or what each parameter selects. The names are self-explanatory to some degree, but the description fails to compensate for the low coverage by explaining parameter roles or relationships.

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 ('one artifact's immutable version history, provenance, attribution, digests, and review states'). It also distinguishes itself by stating it does not return stored bytes, which sets it apart from sibling tools like prepare_artifact_download.

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 this tool by explicitly excluding stored bytes, implying it is for metadata/history retrieval rather than content download. However, it does not explicitly name alternative tools or state when not to use it, missing a direct comparison.

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 no destructive actions, so the baseline safety profile is covered. The description adds behavioral specifics beyond annotations: it enumerates the exact types of data returned (status, progress, errors, version IDs, protected preview URLs) and the notable exclusion of source code. This gives the agent a clearer picture of the tool's output 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 two sentences: the first lists the key output categories in a compact list, and the second clarifies an important exclusion. It is front-loaded with the action and resource, contains zero filler, 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 read-only tool with a single parameter and no output schema, the description is comprehensive enough. It tells the agent exactly what to expect (status, progress, errors, version IDs, preview URLs) and what not to expect (source code). Combined with the rich annotations and schema description, there are no significant gaps in context.

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

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

Schema description coverage is 100% for the only parameter (job_id), and the schema description clearly explains its origin ('returned by build_from_conversation'). The tool description adds no additional parameter details, but since the schema already provides full coverage, a baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Get' and clearly identifies the resource ('one build's current status, progress, errors, completed version IDs, and protected preview URLs'). It also explicitly states what it does not return ('Does not return generated source code'), which distinguishes it from other tools that might return source artifacts. This is a precise and well-scoped purpose.

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

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

The description implies clear usage: use this tool to fetch build status and related details. It also provides a 'when-not' clue by stating it does not return source code. However, it does not explicitly name alternative tools (e.g., 'use get_project for project-level info'), so it falls short of a 5 but still offers clear context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context by enumerating the exact components returned and explicitly stating that generated source code is not returned, which goes beyond the structured annotation data.

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

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

Two sentences, front-loaded with the core action and expected payload, followed by a clarifying limitation. There is no redundancy or unnecessary detail.

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 tool with a single parameter and no output schema, the description sufficiently explains the response contents and key limitations. It gives an agent enough information to decide whether to invoke this tool and what to expect.

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

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

The input schema fully documents the single parameter with a UUID format, pattern, and description. Schema description coverage is 100%, so the description doesn't need to add parameter-level details; the baseline score of 3 applies.

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

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

The description clearly identifies the tool as a read operation for a specific project resource, enumerating the exact returned data (brief, selected pages, active version, compact version history) and explicitly excludes generated source code. This differentiates it from sibling tools like build_from_conversation or get_project_context.

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

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

The description provides a clear context for when to use the tool by listing exactly what is returned and noting that generated source code is not included. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, so it stops short of the highest bar.

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 (readOnly, idempotent, non-destructive), the description discloses a key semantic guarantee: 'Actor kind is explicit; an external agent is never presented as the human account that authorized it.' This is a non-obvious behavioral trait that shapes how the agent interprets results, adding real value over 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 with zero redundancy. The first sentence front-loads the verb and object and lists the covered activity types compactly. The second sentence adds a crucial behavioral nuance without unnecessary words. Every element 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 what the tool does, the scope of activity types, and a critical attribution behavior. It does not explicitly describe the return structure, but the cursor/limit parameters imply pagination, and the timeline concept is clear. Given the lack of an output schema, a bit more detail about the response format could be added, preventing a perfect 5.

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

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

Schema description coverage is 100%: all three parameters (project_id, limit, cursor) have descriptive text, including defaults and max. The tool description does not add any parameter-specific semantics beyond that. Per the rubric, a baseline of 3 is appropriate 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 states a specific verb+resource: 'Read the attributable project timeline' and enumerates the exact scope (human work, external MCP agents, builds, versions, feedback, and workspace pins). This clearly distinguishes it from siblings like wait_for_project_activity (which waits) and get_project (which fetches a single project), so it is specific and differentiable.

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: whenever a comprehensive, cross-entity activity timeline is needed. However, it does not explicitly name alternatives or exclusion conditions (e.g., 'for only feedback, use list_project_feedback'), so it falls short of the explicit when/when-not guidance that would earn a 5.

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

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

Annotations already indicate 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 disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context by stating 'Disabled shares return no URL,' which is not obvious from annotations. It also clarifies the read nature, but it does not provide details about error cases or authentication requirements, though the annotations lower the burden.

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

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

The description is two concise sentences with no wasted words. It front-loads the core purpose with a verb and provides a key edge case in the second sentence. Every sentence adds distinct 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?

The tool is relatively simple with 3 parameters, no output schema, and strong annotations. The description covers the core function, the scope ('one exact saved version'), and a key behavioral edge case (disabled shares return no URL). However, it is vague about the 'durable' nature, does not describe the return format, and leaves the 'page' parameter unexplained, so there is still a minor completeness gap.

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

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

Schema description coverage is 0%, and the description provides no parameter-specific meaning. While project_id and version_id are reasonably self-explanatory, the optional 'page' parameter is entirely ambiguous, and the description does not clarify the relationship between parameters or which are required. The description fails to compensate for the lack of schema descriptions.

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

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

The description uses a specific verb ('Read') and clearly identifies the resource ('durable sharing state and current URL') plus a scope qualifier ('for one exact saved version'). It distinguishes this read tool from the sibling create_version_share_link and revoke_version_share_link 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 the tool is for reading existing share state, but it does not explicitly state when to use it over alternatives like create_version_share_link or revoke_version_share_link. There are no exclusionary guidelines or alternative tool names mentioned, so usage is only implied.

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

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

Annotations already 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 readOnly, idempotent, and non-destructive hints. The description adds value by specifying the return content: 'project/version identity and attribution, never generated source.' This discloses what the response includes and excludes, going beyond the structured annotations.

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

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

The description is two sentences, front-loading the main purpose and then adding return details. Every sentence provides distinct information with no redundant filler, making it appropriately sized 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 simple list operation, rich annotations, and full schema descriptions, the description sufficiently covers the tool's behavior. It clarifies the output's nature (identity/attribution, not source) but does not specify the exact return structure, which is acceptable without an output schema. However, the phrase 'waiting for a separately delegated reviewer' slightly under-represents the status parameter which can also list approved and rejected requests.

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% description coverage, with both 'limit' and 'status' having clear descriptions. The tool description does not add extra meaning to the parameters—it only mentions 'waiting for a reviewer' which aligns with the default 'pending' status, but does not elaborate on limit or status semantics beyond the schema.

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

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

The description clearly states it lists exact saved versions waiting for a separately delegated reviewer, which is a specific verb+resource combination. It distinguishes itself from related tools by clarifying it returns version/project identity and attribution, never generated source, setting it apart from artifact-focused tools like list_artifact_approval_requests.

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

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

The description provides clear context: use this to list version approval requests, with a status filter for pending/approved/rejected/all. It does not explicitly name alternatives or exclusions, but the phrase 'exact saved versions' and the mention of attribution signals it is for version reviews rather than artifacts.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, so the description's added context about requiring 'separately delegated artifact review authority' provides useful behavioral nuance beyond annotations. It also clarifies the scope includes versions with any human review decision, not just pending ones.

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

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

The description is a single concise sentence that front-loads the action and resource, then adds a necessary authorization prerequisite. Every word earns its place with no redundancy or irrelevant detail.

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 optional filters, the description adequately states the core function and authority requirement. However, it leaves some gaps: no mention of the optional project_id filter (though schema hints at it) and no distinction from the similarly named sibling 'list_approval_requests' beyond 'artifact.' Given the tool's simplicity and available annotations, it is mostly complete but could be slightly more explicit about return value or filtering options.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning, but it does not mention the 'status' or 'project_id' parameters at all. The schema's enum and default provide some semantics, but the description fails to explain how these filters affect results, leaving potential confusion about the tool's configurable 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 lists exact artifact versions with human review decisions, using a specific verb (list) and resource (artifact versions). It distinguishes itself from sibling 'list_approval_requests' by explicitly scoping to artifacts rather than general approval requests.

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

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

The description implies usage for artifact review scenarios and notes a prerequisite (delegated authority), but it does not explicitly state when to use this tool versus alternatives like 'list_approval_requests' or provide exclusion criteria. The guidance is implied through the artifact-specific naming rather than explicit differentiation.

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 covered. The description adds valuable context beyond annotations: artifacts are 'durable', the operation returns only the 'latest immutable version', and it explicitly says 'without returning stored bytes', which clarifies the response scope. This enriches the agent's understanding without contradiction.

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

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

The description is a single, front-loaded sentence of 13 words. It starts with the verb 'List' and resource, then adds two concise qualifiers ('durable' and 'without returning stored bytes'). Every word earns its place, making it highly efficient 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 parameter, no output schema), the description adequately covers the core behavior: listing artifacts and their latest versions without returning bytes. It does not specify response fields, pagination, or ordering, but for a simple list operation with strong annotations, this is sufficient. Some might expect mention of prerequisite permissions, but the readOnlyHint mitigates that 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 0%, and the description does not mention project_id at all. Although the single parameter is self-explanatory from the tool name and schema, the description fails to compensate for the lack of schema documentation and does not explicitly connect the parameter to the tool's action. The agent is left to infer that project_id identifies the project for which artifacts are listed.

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

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

The description clearly states a specific action ('List') on a specific resource ('durable project artifacts and each latest immutable version') and explicitly distinguishes itself from sibling tools by noting it does not return stored bytes. This differentiates it from get_artifact and prepare_artifact_download, making the purpose unambiguous.

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

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

The description implies usage for listing artifact metadata without retrieving content, but it does not explicitly state when to use this tool versus alternatives like get_artifact or prepare_artifact_download. There is no direct comparison or exclusion, so guidance is only implied 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 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds useful behavioral context: it returns status and summary but not full Limits or run traces. This helps set expectations about the output scope, going beyond what annotations alone convey.

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

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

The description is only two sentences, front-loads the core purpose, and adds a clarifying scope/limitation line. Every word earns its place with no redundancy.

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

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

For a simple list tool with one parameter, annotations covering safety, and no output schema, the description is complete. It states what is returned (status and summary), what is not returned (limits, traces), and the project scoping, giving an agent enough to select and 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?

Schema coverage is 100%, with the only parameter project_id having a clear description. The tool description does not add further parameter-level details, but none are needed given the schema already documents the parameter fully.

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

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

The description clearly states the tool lists the authorizing account's built-in Agents for a single readable project, which is a specific verb+resource+scope. It distinguishes itself from sibling tools like get_project and list_projects by focusing on project-scoped agents, and from get_agent/run_project_agent by being a listing operation.

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

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

The description provides clear context: it lists agents assigned to one readable project and notes that it reveals status/summary rather than full Limits or run traces. This implies when to use it and what to expect, though it does not explicitly name alternative tools for those deeper needs.

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

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

Annotations already declare the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds content context about the feedback being 'page-anchored' and 'with explicit human or external-agent attribution', but it does not disclose additional behavioral traits such as pagination, filtering defaults, or return structure beyond what the schema already provides. 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 that immediately states the action (Read) and the target (page-anchored review feedback for versions in a project). It is concise and front-loaded, with every word contributing 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?

The tool has strong schema coverage and annotations, and the description clearly communicates the core purpose and scope. However, since there is no output schema, a brief mention of the return format (e.g., a list of feedback items) would have made it complete. The description is still adequate for a simple read-only 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 descriptions for 'project_id' and 'include_resolved' achieve 100% coverage, so the baseline is 3. The description does not add any additional meaning to the parameters beyond what the schema already explains, such as the default behavior of 'include_resolved' or the format of 'project_id'.

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 'page-anchored review feedback for versions in a project'. It further distinguishes this from other feedback tools by noting 'explicit human or external-agent attribution', which differentiates it from generic feedback operations and sibling tools like add_project_feedback and resolve_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 clearly implies the use case: reading review feedback for project versions. It provides context about what the tool returns (page-anchored feedback with attribution), but it does not explicitly state when to use this versus alternatives such as add_project_feedback or resolve_project_feedback, nor exclude other feedback-related tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description only needs to add extra behavior. It adds 'shared workspace' and 'explicit attribution,' which provide some context about scope and output. However, it omits details like pagination, ordering, or whether the full content or just metadata is returned.

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, short, front-loaded sentence: 'Read shared workspace notes and http(s) links, with explicit attribution.' Every word earns its place, with no redundant or filler 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?

With no output schema, the description should clarify the return value; it does indicate the returned items (notes and links). However, it remains vague about project scoping, result format, and attribution details. For a simple list tool, this is adequate but minimal.

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 mention the project_id parameter or explain how it relates to the operation. The tool name and property name infer the meaning, but the description fails to compensate for the schema's lack of detail.

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

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

The description uses the specific verb 'Read' and specifies the resource as 'shared workspace notes and http(s) links,' which makes the tool's purpose clear. The title 'List workspace pins' reinforces this. It distinguishes from sibling add/remove tools by implying a read operation, though it doesn't explicitly name them.

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

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

No guidance is given on when to use this tool versus alternatives. The description does not mention that it operates per project (despite the project_id parameter) or exclude scenarios where other list tools (e.g., list_projects) would be more appropriate.

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

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

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?

Beyond the annotations (readOnlyHint: true, etc.), the description discloses important behaviors: the URL expires in five minutes, it targets a single immutable version, and cached bytes never enter MCP model output. This adds meaningful context about side effects and privacy, going beyond what the 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?

The description is two sentences, front-loaded with the core purpose, and each sentence adds distinct value. There is no fluff or redundant restatement of the tool name. It is efficiently written.

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 main purpose and a key behavioral guarantee, but lacks details about the return value (e.g., does it return just the URL or a structured object?) and does not specify prerequisites such as whether the artifact must already exist. For a simple 3-param tool with no output schema, this is adequate but with notable 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?

With schema description coverage at 0%, the description must explain the three parameters, but it does not. It mentions 'one immutable artifact version' but never clarifies the distinct roles of project_id, artifact_id, and artifact_version_id, nor their relationship. This leaves the agent to infer from parameter names alone, which is insufficient.

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 primary action: 'Create a five-minute download URL for one immutable artifact version.' This is a specific verb (create), resource (artifact download URL), and scope (one immutable artifact version). It distinguishes itself from sibling tools like get_artifact by emphasizing the download URL creation and the privacy guarantee about bytes not entering model output.

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 a use case (downloading an artifact without exposing bytes to the model) but does not explicitly say when to use this tool versus alternatives like prepare_version_export or get_artifact. There is no explicit exclusion or comparison, so the guidance is only implied, not clearly stated.

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

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

Annotations only indicate readOnlyHint=false and non-idempotent, so the description carries the burden of explaining behavior. It discloses five-minute expiry, exact bytes, pending review, and no replacement before approval – rich context beyond structured data.

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

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

Two sentences, front-loaded with the action, each sentence adds new information without redundancy. The format is efficient and easy to parse.

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

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

The description covers the essential behavioral contract (review, expiry, immutability) but does not elaborate on the full workflow, such as how to create new vs version artifacts or the return value. Since no output schema exists, some of this is implied but not explicit.

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

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

Schema coverage is only 20%, and the description adds minimal parameter meaning beyond 'exact bytes', which implies sha256/byte_size. It does not explain key parameters like artifact_id, parent_version_id, or review_note, so the low coverage is not compensated.

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') and resource ('five-minute PUT URL'), and clearly distinguishes from siblings by noting the review workflow ('enters pending review', 'never replaces'). This separates it from download and approval 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 states the core use case (creating upload URLs) and specifies the review context for external agents, but does not explicitly name alternative tools or exclusions. The sibling set implies the workflow, but no direct 'use X instead' guidance 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 indicate readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral details: the URL expires in five minutes and the source is never embedded in MCP model output. It does not contradict 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 concise sentences, with the main action front-loaded. Every word earns its place, and there is no unnecessary information.

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

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

For a tool with two simple UUID params and no output schema, the description is quite complete. It covers the key purpose, the temporary URL behavior, and the external delivery route. The only minor gap is the lack of explicit return-value description, but this is partially implied by the term 'download URL.'

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 compensate by explaining the meaning or relationship of project_id and version_id. The parameter names are self-explanatory to some degree, but the description fails to clarify that project_id is required to locate the version, leaving a gap for agents.

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 specific action: 'Create a five-minute download URL for an exact saved version.' It distinguishes this tool from siblings like get_version_share_link and prepare_artifact_download by emphasizing the exact saved version and the external download route.

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: it creates a temporary download URL for a version, and clarifies that the source is delivered via the download route, not embedded in MCP output. It does not explicitly name alternatives or exclusions, but this context is sufficient for an agent to understand when to use 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?

Beyond the annotations (idempotent, non-destructive), the description adds valuable behavioral detail: it consumes one persisted project iteration, returns an asynchronous job_id, and preserves the base source as currentCode. This goes beyond what annotations alone communicate, making side effects and async behavior clear.

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

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

The description is two sentences, front-loaded with the core purpose and followed by key behavioral notes. There is no filler, and every sentence contributes meaningful guidance.

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 captures the main operation, side effect (consumes iteration), and async return (job_id). Since there is no output schema, it briefly notes the return type but does not explain how to poll or what the job does afterward, which is a minor gap for a tool with this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific semantics beyond what the schema already provides; it only reinforces that feedback should be concrete, which aligns with the schema's description but adds no new information.

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') with a clear resource ('one protected child version') and defines the inputs ('saved base version and concrete review feedback'). It also clarifies the outcome (preserves base source, consumes an iteration, returns an async job), which distinguishes it from sibling tools like build_from_conversation or approve_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 when to use this tool: when you have a saved base version and concrete review feedback. However, it does not explicitly name alternatives or state when not to use this tool versus build_from_conversation or other version-creation tools, so guidance is only implied.

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

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

Annotations already declare idempotentHint true, and the description repeats this with 'Repeating the same decision is idempotent,' adding slight clarification. It also adds the behavioral context of 'pending immutable' state, which is useful. However, it doesn't disclose outcomes like notification, reversibility, or what happens after rejection.

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 consists of two short sentences, front-loading the core action. Every word earns its place, and the idempotency clarification adds value despite being in annotations, because it specifies 'same decision'.

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

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

The tool is simple (two params, no output schema) and annotations cover idempotency and safety. The description clarifies purpose and state, but leaves request_id unexplained and does not describe post-rejection behavior. Given the simplicity, it is minimally complete but with clear gaps.

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

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

With 0% schema description coverage, the description must compensate but only says 'with useful feedback,' which vaguely maps to the note parameter. It does not explain request_id, what it refers to (e.g., an approval request ID), or how to obtain it. This is a significant gap for two required 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 'Reject one pending immutable artifact version with useful feedback,' which combines a specific verb (reject), resource (artifact version), and scope (pending, immutable). This distinguishes it from siblings like reject_version (project versions) and approve_artifact_version, making the purpose unambiguous.

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

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

The description implies usage context by specifying 'pending immutable artifact version,' but it does not explicitly mention alternatives or exclusions. There is no guidance on when to choose this over reject_version or approve_artifact_version, and no mention of when not to use it.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds meaningful behavioral context: restoration of the active parent and retention in immutable history, which goes beyond the annotation signals and clarifies the precise consequences of the rejection.

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 main purpose, and each clause adds essential behavioral details. There is no redundancy or filler, 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 4-parameter schema and no output schema, the description covers the key behavioral implications (parent restoration, immutable history) and authority prerequisite. It could mention potential outcomes like error conditions, but it is largely complete for a rejection tool with these annotations.

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

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

Schema description coverage is 100%, with each parameter (project_id, version_id, confirmation, decision_note) already documented clearly. The tool description adds no additional parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the action 'reject' on the resource 'one saved version', and the effect of restoring the parent if active. It effectively distinguishes this tool from siblings like approve_version by focusing on rejection and its specific behavioral consequence.

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

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

The description implies usage context through 'Use separately delegated review authority', indicating a prerequisite of special permission. However, it does not explicitly contrast with alternatives (e.g., approve_version, reject_artifact_version) or state when not to use 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 declare destructiveHint=true and idempotentHint=true. The description only repeats 'idempotent' without adding new behavioral context, such as whether the operation is reversible, required permissions, or what happens to the pin after removal.

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 with no filler. It states the core action and a critical property (idempotency) efficiently, earning a perfect score for conciseness.

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

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

For a simple destructive operation with two obvious parameters and no output schema, the description is minimally sufficient. However, it omits details about return values or error behavior, which might be needed for full situational awareness.

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

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

Schema description coverage is 0%, but the description does not explain the parameters. While pin_id and project_id are inferable from the tool name, the description provides no explicit semantics, leaving the AI agent to guess the role of each UUID.

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'), making it distinct from a bulk removal. It does not explicitly reference sibling tools, but the verb+object 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 provides no explicit guidance on when to use this tool versus alternatives. The only usage hint is the idempotency note, which implies retries are safe, but it does not mention exclusions or contrast with related tools like add_project_pin or list_project_pins.

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 description only needs to add context. It adds useful behavioral details: returns protected preview and access-checked workspace links, without source code. This goes beyond the annotations by describing the output's security and access characteristics.

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, each contributing distinct value: purpose, usage, and output/security. No filler or repetition, making it both 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?

For a simple read-only tool with two well-documented parameters and no output schema, the description fully covers what the tool does, when to use it, and what it returns. 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?

The input schema provides 100% coverage with descriptive parameter texts ('Project containing the saved version' and 'Saved version to display'). The description does not add further meaning to the parameters, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool renders an interactive, read-only card for one saved version, with a specific verb and resource. It also distinguishes the tool from siblings by noting it provides protected preview and workspace links without source code.

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

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

The description gives explicit usage context: 'Use after get_build or get_project when the user wants to see, open, or share the result.' This is a clear when-to-use, but it does not explicitly mention when not to use or name alternatives, so it stops short of the highest bar.

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 destructive, non-read-only, idempotent operation. The description adds the owner-only authorization requirement and the dual resolve/reopen capability, providing useful context beyond the structured annotations. No contradiction.

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

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

The description is a single sentence with no redundancy, front-loading the core action. It is efficient, though it could slightly expand on parameter semantics without becoming verbose.

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 and minimal behavioral disclosure beyond annotations, the description leaves gaps: no side effects, no parameter explanations, and no guidance on when to use this over sibling feedback tools. It is not complete enough for an agent to confidently decide when to invoke it.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explain the `resolved` parameter's meaning or default behavior, nor the purpose of the UUID identifiers beyond their names. The agent must infer that resolved=true resolves and false reopens.

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

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

The description clearly states a specific action ('resolves or reopens') on a specific resource ('one saved feedback item'), and adds an owner-only restriction. This distinguishes it from sibling tools like add_project_feedback and 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 implies usage in a review context ('Owner-only review decision') but does not explicitly state when to use this tool versus alternatives. It lacks exclusions or direct comparisons to other feedback tools.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds value beyond that by specifying exactly what is destroyed (all public and code-protected URLs) and adding a behavioral nuance: re-publishing a protected link rotates its code. This gives the agent useful expectations about the tool's side effects without contradicting the annotations.

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

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

The description is concise and front-loaded. The first sentence states the core action and target, and the second sentence provides a relevant behavioral detail. No filler or redundancy; both sentences earn their 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 primary purpose and one behavioral nuance, but does not address prerequisites, error conditions, or the idempotency_key's purpose. Given it is a destructive mutation with no output schema, a bit more detail would improve completeness, though the annotations mitigate some gaps.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It does not mention project_id, version_id, or idempotency_key at all. While the parameter names are self-explanatory, the description adds no meaning beyond the schema's bare names, and it fails to explain the critical idempotency_key requirement. This is a significant gap.

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

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

The description clearly states the verb ('Disable') and the exact resource ('every existing public or code-protected URL for one exact saved version'). It is immediately distinguishable from sibling tools like get_version_share_link and create_version_share_link, which are about retrieving or creating links rather than revoking them. The added note about re-publishing a protected link rotating its code further clarifies the tool's specific 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 gives a clear context for use: you invoke this to disable share links for a specific saved version. The phrase 'for one exact saved version' implies a limitation (not for all versions) and aligns with typical usage. However, it does not explicitly mention when to prefer this over the create/get link siblings, though the action is self-evident.

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 important behavioral context: immutable saved Limits, project access, account fuse, and online Engine requirement are enforced server-side. This goes beyond the annotations (which only indicate side effects and idempotency) by warning that limits cannot be changed and that the engine must be online.

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 key constraints. No filler; every clause adds value, from 'already test-ran and armed' to 'enforced server-side.'

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 purpose, prerequisites, and server-side enforcement, which is sufficient for selecting the tool. It doesn't explain return values or troubleshooting, but there is no output schema and the annotations provide idempotency context, making it adequately complete for a queue/execution 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 already covers all parameters with 100% description coverage (task, model, agent_id, project_id, idempotency_key each have descriptions). The tool description does not add parameter-specific meaning, 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 uses a specific verb ('Queue real execution') and clearly identifies the resource ('project-linked Agent') that has been 'test-ran and armed.' This distinguishes it from siblings like build_from_conversation or refine_project, which focus on creating or refining rather than executing.

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

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

It states the prerequisite that the Agent must be 'already test-ran and armed,' indicating this tool is for real execution after preparation. It doesn't explicitly name alternative tools, but the context implies using build tools first; this is clear but not as explicit as naming alternatives.

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

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

The description adds 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description adds meaningful behavior: the 20-second timeout limit, the oldest-first ordering, and the resync_required fallback logic. It also explains cursor semantics, which is valuable for correct invocation.

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

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

Three sentences, each carrying essential information: timeout, event ordering, and resync behavior. No filler or repetition. The structure is front-loaded with the core action and then clarifies response ordering and edge-case handling.

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 polling tool with no output schema, the description explains the key behavioral aspects (blocking, ordering, resync) and is sufficient for an agent to use it correctly. It could be slightly more explicit about the response envelope (e.g., timed_out flag), but the timeout_seconds parameter description hints at it, so the gap is minor.

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

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

The input schema already provides 100% parameter coverage with detailed descriptions for project_id, after_cursor, limit, and timeout_seconds. The description does not add much beyond what the schema states, so the baseline of 3 applies. It does reference head_cursor/next_cursor indirectly, but those concepts are already in the schema for after_cursor.

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: wait up to 20 seconds for project events newer than a cursor. It clearly distinguishes the tool from siblings by describing its blocking behavior and the order of returned events, which sets it apart from immediate-fetch tools like get_project_activity.

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

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

It explicitly references an alternative in a specific condition: 'If resync_required is true, paginate get_project_activity instead of advancing the cursor.' It also provides context on why to use this tool ('so an outside agent can process them in order'). This gives clear when-to-use and when-not-to-use guidance.

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