2ools

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

Given annotations are present, the description adds useful context by explicitly stating the operation is a write that does not alter source or approve the version. It does not detail every side effect (e.g., reply behavior), but it covers the primary behavioral distinction.

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

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

Two short sentences, front-loaded with the purpose and immediately adding a key non-effect. 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?

The tool has 9 parameters and no output schema; while the description captures the main purpose and exclusions, it omits support for replies and positioning (x/y/page/label), making the context incomplete for proper use.

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

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

Schema coverage is only 44%; five parameters (project_id, version_id, page, label) lack schema descriptions, and the description does not compensate. It only clarifies 'comment' and 'project version' implicitly, leaving x/y/page/label and reply_to_feedback_id semantics unexplained.

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

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

The description uses a specific verb ('Add') and resource ('attributable review comment to a saved project version'), and further distinguishes itself by stating it does not modify source or approve the version, setting it apart from 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 implies when to use (adding a review comment) and includes a clear exclusion ('does not modify source or approve the version'), but it does not explicitly name alternative tools such as approve_version or resolve_project_feedback.

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

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

Annotations already cover non-read-only and non-destructive behavior. The description adds useful context with 'safe http(s)' (suggesting URL validation) and 'attributable' (user attribution), but it does not disclose side effects, authorization needs, or idempotency semantics despite a required idempotency_key.

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, compact sentence with no filler and is front-loaded. It is concise but sacrifices necessary detail 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?

With 9 parameters, no output schema, and no return-value description, the description is too sparse for reliable invocation. Coordinate parameters, surface choices, and return behavior are completely unaddressed.

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% (just idempotency_key). The description maps kind to note/link and implies url for links, but leaves x, y, surface, version_id, label, and project_id unexplained, forcing an agent to rely on names alone.

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—adding a note or safe http(s) link to a shared project workspace—and the 'pin' concept is clarified as note/link. This distinguishes it from add_project_feedback and pin-management tools like list_project_pins/remove_project_pin, though 'attributable' remains slightly ambiguous.

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

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

No guidance is provided for when to use this tool versus alternatives such as add_project_feedback or remove_project_pin. The phrase 'shared project workspace' offers only minimal context and there are no exclusions or alternative recommendations.

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

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

Annotations already cover idempotency and read-only/destructive hints. The description adds the context that it 'make[s] it current' and that the version is 'pending immutable', which provides useful behavioral context beyond annotations. The idempotency statement is redundant with the annotation but not contradictory.

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, consisting of two short sentences. Every word adds value: it states the primary action and a key behavioral property (idempotency). No filler or irrelevant information.

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

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

Given the simple tool (2 params, no output schema, atomic action), the description is minimally adequate but lacks important context: how to identify the pending request, the meaning of 'make it current' (e.g., replaces the current version), and the absence of usage guidance. Annotations fill in safety hints but not workflow context.

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

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

Schema description coverage is 0%, and the description does not explain the parameters 'request_id' or 'note'. It is not clear from the description that 'request_id' identifies the pending approval request, nor what the 'note' is for. The title hints at 'exact artifact version' but does not compensate for the missing parameter documentation.

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

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

The description clearly states the action: 'Approve one pending immutable artifact version and make it current.' This specifies the verb (approve), resource (artifact version), and scope (one pending version). It does not explicitly distinguish from the sibling tool 'approve_version', but the 'artifact' qualifier helps disambiguate.

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

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

No explicit guidance is given about when to use this tool versus alternatives like 'reject_artifact_version' or 'approve_version'. The context of approving a pending artifact is implied but there is no mention of alternatives or prerequisites (e.g., listing pending requests first).

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds behavioral context beyond annotations by mentioning the need for 'separately delegated review authority' and by clarifying that the operation does not publish, export, or change project permissions. This provides useful extra transparency 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 exactly two sentences. The first sentence front-loads the core action and condition; the second lists relevant exclusions. Every sentence earns its place with no redundancy or fluff, 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?

For a mutation tool with no output schema, the description covers purpose, authority, and non-effects. However, it does not explicitly state what happens to the previously active version (e.g., whether it is replaced or archived) or mention any preconditions like the version being in a reviewable state. Given the annotations provide destructiveness and idempotence, these are minor gaps, but the overall context is fairly complete.

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

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

Schema description coverage is 100%, with each parameter already having a clear description (project_id, version_id, confirmation, decision_note). The tool description adds no additional parameter semantics, so the baseline score of 3 applies because the schema fully handles parameter meaning.

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

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

The description uses a specific verb 'approve' with a clear resource 'one saved version' and states the effect: 'make it the project's active version'. It also differentiates from siblings like approve_artifact_version by explicitly noting what it does not do (publish, export, change permissions). This gives precise purpose and 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 begins with 'Use separately delegated review authority', which clearly states the prerequisite and contextual condition for using this tool. It also provides exclusions ('Does not publish, export, or change project permissions'), but does not explicitly name alternative tools for those actions. This is clear context but lacks direct alternative naming.

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 destructiveHint=false, so no need to restate mutation. The description adds valuable behavior: 'durable build' signals async execution, 'protected preview' hints at access control, and explicit return of project_id/job_id clarifies side effects. 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 exactly two sentences, front-loaded with the primary purpose and immediately followed by return-value and follow-up details. 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?

Given the complexity (16 params, no output schema), the description adequately covers return values and the async nature of the build. It does not enumerate prerequisites like calling list_build_systems, but the schema handles parameter origins. Overall, it is sufficient for an agent to understand the tool's core workflow.

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

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

Schema description coverage is 100%, so the schema already documents all 16 parameters. The description's phrase 'structured conversation brief' loosely maps to conversation_summary but adds no parameter-level meaning beyond what the schema provides, matching the baseline for full coverage.

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

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

The description uses a specific verb ('Create'), names the resource ('2ools project'), and adds a concrete second action ('queue one durable build'). It clearly differentiates from siblings like get_build or refine_project by stating exactly what is created and that a build is queued.

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 have 'a structured conversation brief' and provides a follow-up action ('use get_build'), but it does not explicitly state when not to use this tool or name alternatives among siblings like refine_project or run_project_agent.

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

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

Annotations already indicate destructive and idempotent hints, but the description adds crucial context: it closes durable run history and preserves terminal truth. This clarifies the exact scope of destruction and idempotency, complementing the annotations 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 two sentences with no redundant words. It front-loads the primary action and immediately provides important behavioral boundaries, making it 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 complexity (4 required params, destructive and idempotent behavior) and no output schema, the description fully covers what the tool does, when it is effective, and what side effects occur. It is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% description coverage for all four parameters, so the schema already provides complete parameter semantics. The description adds no additional parameter meaning, which is fine given the baseline of 3 for high coverage.

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

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

The description opens with a specific verb and resource: 'Stop one queued or running Agent execution' and 'close its durable run history'. This clearly distinguishes it from sibling tools like cancel_build by focusing on Agent runs rather than builds.

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

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

It explicitly states when to use the tool (for queued or running executions) and, in the second sentence, when not to use it (completed, failed, stalled, or already-canceled runs are unaffected). It does not name alternative tools, so it falls 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 flag destructive and idempotent hints, but the description adds context that completed versions are not deleted and terminal builds are left unchanged. This goes beyond the annotations, though it could mention post-cancellation effects (e.g., return value) for fuller transparency.

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

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

Two sentences with no fluff. The first sentence states the action and scope, the second adds clarifying exclusions. Information is front-loaded and every clause earns its place.

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

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

For a single-parameter destructive tool with annotations, the description covers the core behavior, exclusions, and alternative tool. A small gap on return value or further effects, but no output schema exists and the provided context is sufficient for an agent 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?

The input schema fully documents the only parameter (job_id) with a description ('Build job ID returned by build_from_conversation'). The tool description adds no further semantic value, so a baseline score of 3 is appropriate given the high schema coverage.

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

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

The description uses a specific verb ('Cancel') and clearly scopes the action to 'a queued or running non-Agent 2ools build.' It also distinguishes from the sibling tool 'cancel_agent_run,' 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?

Explicitly states when to use: only for queued/running builds, not completed or terminal. It also names the alternative for governed Agent execution ('cancel_agent_run'), meeting the 'when-not/alternatives' criterion.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond these: ending the lease is a mutating action, and ambiguous external effects are never auto-retried, always waiting for reconciliation. This aligns with the idempotentHint and provides a critical operational rule not exposed by the annotations.

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

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

Two sentences, front-loaded with the primary purpose and followed by a single key behavioral rule. No wasted words; every sentence adds value. The structure is clean and easy to scan.

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

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

This is a complex tool with 13 parameters, no schema descriptions, no output schema, and sparse annotations. The description gives a high-level purpose and one behavioral rule, but fails to explain parameter semantics, what a checkpoint should contain, when to choose waiting vs blocked, or what the response looks like. For such a parameter-heavy tool, the description is not nearly sufficient 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?

With schema description coverage at 0%, the description bears full responsibility for explaining the 13 parameters. While it indirectly hints at disposition (waiting/blocked) and effect_state ('external effects'), it does not explicitly define session_id, checkpoint, idempotency_key, or the many metrics fields. The description provides almost no parameter-level guidance, leaving agents to guess the purpose and format of these inputs.

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 core action: 'End the current lease with a compact continuation checkpoint' and also covers alternate disposition states ('waiting or blocked'). This specific verb+resource construction sufficiently distinguishes it from sibling tools like heartbeat_work_session or submit_work_session, though it does not explicitly name those alternatives.

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

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

The description implies usage by saying 'or place work in an explicit waiting or blocked state', suggesting when to use different dispositions. The second sentence gives a rule: ambiguous external effects should wait for reconciliation and never be auto-retried, which is useful guidance. However, there is no explicit comparison to alternative tools or clear prerequisites for using this over siblings like continue_project or heartbeat_work_session.

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 adds atomicity, a five-minute renewable lease, and an immutable budget snapshot, giving useful operational context. It does not contradict the annotations, which already indicate idempotency and non-destructiveness.

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 every phrase adding meaningful detail. No filler or redundancy.

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

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

The description covers the core action and key outcomes, but with no output schema it omits parameter semantics, failure/error behavior, and renewal mechanics. It is adequate but not fully complete for a tool with three 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%, so the description should compensate, but it only loosely ties assignment_id to an 'open assignment' and says nothing about idempotency_key or input_refs. Parameter meanings are largely left to names and schema structure.

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 'claim' with a clear resource 'one open assignment' and the resulting outcomes (lease, budget snapshot). This distinguishes it from sibling tools like create_work_assignment, decide_work_assignment, and heartbeat_work_session.

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 used when an agent wants to claim an open assignment, but it does not explicitly contrast it with alternatives or state when not to use it. Usage guidance is present only by implication.

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

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

Annotations already declare read-only and idempotent behavior, lowering the bar. The description adds valuable behavior beyond annotations: it explicitly states that source is not returned and lists exactly which metadata fields are reported (lineage, review state, page additions/removals, byte sizes, SHA-256). This goes beyond the structured hints.

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

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

The description is two sentences: the first states the core function and key constraint, the second lists the output fields. It is front-loaded, contains no redundant words, and every sentence earns its place.

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

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

For a read-only tool with three parameters and strong annotations, the description covers the what, the safety profile, and the returned metrics. It does not specify the exact response format or pagination, but given no output schema is present, the description is reasonably complete. Slightly more detail about the return structure could earn a 5.

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

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

Schema description coverage is 100%, with each parameter already explaining its role ('Earlier or baseline version ID', 'Later or candidate version ID'). The description does not add additional parameter-level meaning, so the baseline score of 3 applies.

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

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

The description clearly states the verb ('Compare') plus the resource ('two saved versions in one project') and adds a distinguishing constraint ('without returning source'). It also enumerates the specific outputs (lineage, review state, page changes, byte sizes, SHA-256), making the tool's function unambiguous and distinct from version approval/export siblings.

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

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

The context is clearly implied: use this when you need to compare two versions in a project. The description does not explicitly name alternatives or exclusion criteria, but the phrase 'without returning source' hints at when to prefer this over export tools. It stops short of explicit when-to-use vs. sibling tools, so a 4 is 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 valuable behavioral context about host-dependent presentation (opens an inline plan and timeline panel on MCP Apps hosts, returns JSON/text elsewhere). This goes beyond the safety profile provided by annotations.

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

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

Two sentences, no filler. The first sentence lists all return contents, and the second explains host-dependent behavior. Information is front-loaded 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?

The tool is simple (2 params) and annotations provide safety. The description explains what is returned (five data items) and how results are presented across host types. It omits error cases or permission requirements, but given the read-only nature and existing annotations, this is sufficient. No output schema exists, so the description rightly carries the burden of describing outputs.

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 50%: project_id has minimal description ('Readable 2ools project ID'), and response_format lacks description. The description implicitly clarifies project_id as the project selector but does not elaborate on response_format or its values. With partial schema coverage, the description adds marginal value but does not fully compensate.

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

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

The description clearly states the tool returns a project's Living Plan, next useful move, continuity-readiness gaps, latest evidence, and a compact receipt. This is specific and distinguishes it from sibling tools like get_project or get_project_context by listing unique outputs.

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

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

No explicit guidance is provided on when to use this tool versus alternatives. The name and title imply continuation, but there is no mention of alternative tools or when not to use it. The description only explains output and host behavior, not selection 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?

The description adds meaningful behavioral details beyond the annotations: the preview is temporary (expires in 24 hours), free, authless, and read-only. This complements the idempotentHint and destructiveHint annotations. No contradiction; readOnlyHint=false refers to the tool's create effect, while 'read-only' describes the resulting preview artifact.

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 concise sentences, front-loaded with the core action and constraint, and no filler. The explicit 'write the HTML first, then call it' earns its place as a critical usage instruction.

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, lifecycle, and cost/auth, but with no output schema it omits what the caller receives (e.g., preview URL/ID) and what happens when it expires. This is a notable gap for a creation 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?

All three parameters have complete schema descriptions, so the baseline is 3. The description reinforces that html must be a pre-existing complete document, but does not add syntax or format details beyond the schema. The idempotency_key semantics are fully covered by 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 opens with a specific verb ('Turn') and names the resource (a complete standalone HTML document) and the outcome (a temporary, read-only 2ools preview). It clearly distinguishes itself from sibling creation tools by emphasizing that it does not generate the page and operates on HTML already created in chat.

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

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

It explicitly instructs the agent to write the HTML first and then call this tool, establishing a clear prerequisite and ordering. It also states a negative use case ('This tool does not generate the page'), though it does not name alternative 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 declare idempotentHint=true, and the description adds meaningful detail that reusing the idempotency key returns the original result, implying a 'create or recover' behavior. This goes beyond the bare annotation and aligns with the idempotency hint, with no contradictions.

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

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

Two front-loaded sentences with no filler. The core purpose and idempotency behavior are stated efficiently, earning every word.

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

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

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

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

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

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

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

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

The description uses a specific verb ('Create or recover') and resource ('durable public or code-protected link for one exact saved version'). It clearly differentiates from siblings like get_version_share_link (retrieval) and revoke_version_share_link (revocation), and specifies the exactness of the version.

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

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

The description provides clear context for when to use the tool: to create or recover a durable link for a specific saved version, with idempotency recovery. It does not explicitly mention alternatives or when-not-to-use, but the context is well-defined.

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

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

The description adds context beyond annotations by noting the assignment is 'durable' and has 'hard ceilings', implying persistence and enforced limits. With annotations already declaring idempotent and non-destructive hints, this adds some value but does not fully disclose side effects like the return value or behavior on idempotency key reuse.

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

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

The description is a single, front-loaded sentence that avoids redundancy and uses precise terminology. Every part adds meaningful information, 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?

Despite the tool having 10 parameters and no output schema, the description does not explain the return value, prerequisites, or the exact meaning of 'durable'. It also fails to cover important parameters like idempotency_key and due_at, leaving the description incomplete for a create operation 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 0%, so the description must compensate. It mentions 'acceptance criteria' and 'step, time, and spend ceilings' which helps clarify acceptance_criteria, max_steps, max_minutes, and max_spend_cents. However, it leaves many parameters (project_id, idempotency_key, due_at, priority) unexplained, which is insufficient for 10 parameters.

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

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

The description clearly states the tool creates a durable assignment with acceptance criteria and hard step/time/spend ceilings, distinguishing it from siblings like claim_work_assignment or decide_work_assignment. The verb 'create' and resource 'assignment' are explicit, and the mention of 'bounded' and 'durable' adds 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?

No guidance is provided on when to use this tool versus alternatives. Sibling tools such as claim_work_assignment and list_work_assignments exist, but the description does not explain the relationship or when creation is appropriate. The context is implied but not explicitly 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 value beyond the annotations by explaining the behavioral nature of the tool: it either completes or reopens work, and the note should contain 'useful feedback.' It also discloses the authorization requirement. Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, and the description does not contradict these. It could further mention idempotency or failure behavior, but overall it provides meaningful behavioral context.

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

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

The description is exceptionally concise: two sentences that front-load the primary action and include a critical prerequisite. Every word earns its place, with no unnecessary filler or repetition of schema/annotation information.

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

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

The tool has 4 parameters, no output schema, and rich annotations. The description covers the core decision action and authority requirement, but it omits details about expected return values, behavior on invalid input, or the role of idempotency_key in retries. Given the absence of an output schema and zero parameter descriptions, the description is somewhat thin for a complete understanding, though the overall operation is simple.

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 carries the burden of explaining parameters. It indirectly maps 'complete' and 'reopen' to the decision enum values and 'useful feedback' to the note parameter. However, it does not explain assignment_id or idempotency_key. The parameter names are fairly self-explanatory, and the description partially compensates for the lack of schema descriptions, but it is not thorough.

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 with specific verbs: 'Complete submitted work or reopen it with useful feedback.' It identifies the resource as 'submitted work' and distinguishes it from sibling tools like approve_version/reject_version by focusing on work assignments. The title and description together make 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 provides clear context that this is for reviewing submitted project work and explicitly mentions a prerequisite: 'Requires separately delegated work-review authority.' It does not explicitly compare to alternatives like approve_version or reject_version, but the phrasing 'submitted work' and 'work-review authority' implies a distinct use case. This is strong guidance, though not exhaustive.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context by specifying that raw prompts, tool arguments, credentials, and source bytes are not returned, and that run traces are redacted and append-only. This goes beyond the structural hints without contradicting them.

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

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

Two sentences, both purposeful. The first front-loads the action and resource; the second clarifies redactions. No fluff or repetition.

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

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

The description explains the read contents and explicitly lists what is excluded, which is sufficient for a read operation. It does not explain the return format or pagination, but the absence of an output schema and the presence of run_limit in the schema reduce the need for more. Sibling tools are not mentioned, but the scope is clear.

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 descriptions for both agent_id and run_limit, covering 100% of parameters. The description does not add any additional meaning or usage details for these parameters, so it stays at the baseline 3.

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 identifies the resource as 'one Agent' plus the specific data fields: 'saved Limits, trigger, immutable revision summaries, and redacted append-only run traces.' This clearly distinguishes from sibling tools like list_project_agents by explicitly scoping to a single Agent.

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 a single Agent's details by saying 'Read one Agent's...'. This provides clear context, but it does not explicitly state when to use this vs alternatives or mention any exclusions. No alternative tools are named, 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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavior beyond that: it clarifies that the tool does not return stored bytes, which informs the agent about response size/cost. It also enumerates the metadata categories included, giving a fuller picture of the read operation.

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

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

The description is a single sentence, front-loaded with the verb 'Read,' and every clause adds useful information. It is concise and free of filler or redundant restatements of the tool name.

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 2 parameters and no output schema, the description sufficiently explains what the tool returns (version history, provenance, attribution, digests, review states) and what it does not return (stored bytes). Combined with annotations and sibling context, it provides complete guidance for an agent.

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. It only mentions 'one artifact's' which implies artifact_id identifies the artifact, but project_id is not mentioned at all. No guidance is given about the relationship between the two IDs or their purpose beyond what the parameter names already suggest.

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

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

The description uses a specific verb ('Read') and clearly defines the resource as 'one artifact's immutable version history, provenance, attribution, digests, and review states.' It also explicitly distinguishes itself from download tools by stating 'without returning stored bytes,' which differentiates it from siblings 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 conveys clear context: this tool is for reading metadata/history, not for retrieving content ('without returning stored bytes'). It implies when to use it (e.g., when you need history or provenance) but does not explicitly name alternative tools such as prepare_artifact_download or list_artifacts, nor state 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the safety profile. The description adds valuable context beyond those annotations by detailing the specific data returned (status, progress, errors, version IDs, preview URLs) and explicitly noting that source code is not returned. This goes beyond minimal annotation coverage and helps the agent set expectations.

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

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

The description consists of two short sentences that are front-loaded with the core action and resource, and every phrase adds value. The second sentence explicitly states a limitation without fluff. This is a model of 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?

The tool is simple (one required parameter, rich annotations, no output schema). The description fully covers the tool's purpose, return contents, and a key limitation. It is complete enough for an agent to select and invoke this tool correctly without further documentation.

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 for the only parameter, job_id, which is described as 'Build job ID returned by build_from_conversation.' The tool description does not add further parameter-level detail beyond what the schema provides. With high schema coverage, the baseline score of 3 is appropriate; the description adds no extra semantic 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 the verb 'Get' and the resource 'one build', then enumerates exactly what is returned: status, progress, errors, completed version IDs, and protected preview URLs. It also explicitly distinguishes what it does not return (generated source code). This makes it easily distinguishable from sibling tools like cancel_build or 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?

The description provides clear context for when to use this tool: to retrieve a single build's status, progress, errors, version IDs, and preview URLs. It does not explicitly name alternatives or say when not to use it, but the nature of the tool as a read-only query and the explicit exclusion of source code gives sufficient guidance. A score of 4 reflects the lack of direct alternative references.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds valuable behavioral context by specifying the data scope and the source-code limitation, which is not present in annotations. No contradictions with annotations.

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

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

Two sentences, front-loaded with purpose and specific contents. The second sentence is a concise and useful scope clarification. No filler or redundancy.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers the key return components and a limitation. Minor ambiguity around 'selected pages' and 'compact version history' remains, but it is largely complete for its 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?

The schema fully documents the single project_id parameter with description and format, giving 100% schema coverage. The tool description adds no additional parameter-level detail, 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 ('Get') with a clear resource ('2ools project') and enumerates exactly what is returned (brief, selected pages, active version, compact version history). The explicit note about not returning generated source code helps distinguish it from related tools like get_build or get_artifact.

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

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

The description implies usage for retrieving project overview data but does not explicitly state when to use this tool over siblings. The 'Does not return generated source code' provides an exclusion but lacks a named alternative, 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=true, idempotentHint=true, and destructiveHint=false. The description adds a meaningful behavioral nuance: 'Actor kind is explicit; an external agent is never presented as the human account that authorized it.' This goes beyond annotations by clarifying attribution and identity handling, which is valuable for trust and audit.

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 front-loads the primary action and scope, the second adds a distinct attribution guarantee. There is no fluff or redundancy; every word contributes.

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, the description provides a clear picture of the return content (project timeline across activity types) and a key behavioral guarantee (actor attribution). It does not explicitly describe response shape or pagination, but the cursor/limit parameters in the schema implicitly cover that, making this reasonably complete for a list-read tool.

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

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

Schema description coverage is 100%, with all three parameters (limit, cursor, project_id) already well described in the schema. The description adds no parameter-specific semantics beyond the general timeline scope, so the schema carries the burden.

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

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

The description uses the specific verb 'Read' and names the resource as 'the attributable project timeline,' listing concrete content areas (human work, external MCP agents, builds, versions, feedback, workspace pins). This clearly distinguishes it from siblings like wait_for_project_activity, which is about waiting rather than reading.

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 ('Read the attributable project timeline') but provides no explicit when-to-use guidance or alternative tool comparisons. It does not mention when to prefer this over wait_for_project_activity or other list_* tools, leaving the selection partly to inference.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds value by revealing it provides a frozen snapshot and that historical Rulebook text is never guessed after revisions, which is meaningful behavioral context beyond the annotations.

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

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

Two sentences, front-loaded with the primary purpose, and every clause adds substantive detail. No filler or redundancy.

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

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

The description enumerates the components of the returned packet, which compensates for the lack of an output schema. However, some terms like 'source-free' and 'Curator snapshot' are domain-specific and may not be fully self-explanatory; slightly more context could improve completeness for a generic agent.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description does not add parameter-level detail beyond the schema, but it does reinforce the purpose of include_governance_text via 'Rulebook context'. 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 ('Read') and resource ('source-free operating packet') and enumerates the packet's contents, clearly distinguishing it from sibling tools like get_project or get_artifact. The scope is explicit and immediately understandable.

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 context for when to use this tool. However, it does not explicitly name alternatives or state when not to use it, so it lacks exclusions but has 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 and idempotentHint=true, and the description adds value by explaining that the status is 'computed from authoritative Project OS records, never editable checkboxes.' This clarifies the derived nature and the fact that output reflects system state rather than user-set flags. The description enriches behavioral understanding 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, tightly packed with specific output elements and a key behavioral note. It is front-loaded with the action and result, and no sentence is wasted. It is an exemplary concise description.

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

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

For a single-parameter read-only getter with no output schema, the description fully lists the returned components and clarifies the derived, non-editable nature. It covers the essential information an agent needs to understand what the tool returns and how it behaves. The absence of output schema is compensated by the detailed enumeration of result contents.

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 only parameter, project_id, is not described in the tool description, and schema description coverage is 0%. While the parameter name and UUID type are self-evident, the description adds no additional semantics such as format hints, default behavior, or relationship to other fields. It relies entirely on the schema's basic type/pattern 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 explicitly states the tool 'Return derived direction, trade-off, evidence, and continuity status', making the purpose clear. It lists specific output components and contrasts with the sibling 'manage_project_discipline' by noting the status is not an editable checkbox. This clearly distinguishes it from other project-related getters.

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 a computed discipline status rather than managing or editing it, but it does not explicitly state when to use this tool instead of alternatives like 'get_project' or 'manage_project_discipline'. No exclusions or alternative recommendations are named, so guidance is only contextual.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds context about the 'bounded canonical' nature and server-derived health, but does not discuss potential caveats like rate limits, error conditions, or edge cases in pagination. No contradiction with annotations detected.

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 front-loads the main purpose and then efficiently lists the view options. It is somewhat dense with comma-separated items, but every phrase adds meaningful information without wasted words. The structure is acceptable given the need to summarize multiple view modes.

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

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

Given the tool has 4 parameters, no output schema, and multiple view modes, the description gives a useful high-level overview but omits important details: the exact shape of each view, how the default view works (though the schema sets default to 'contract'), and how pagination parameters (limit/cursor) apply across the paginated slices. It is adequate for a read-only tool with strong annotations but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It describes the view options semantically (e.g., 'active Goal Contract' likely maps to the 'contract' enum, 'goals', 'templates', 'scope-change', 'history'), and mentions 'paginated' and 'slice' which hint at limit/cursor usage. However, it does not explicitly map the items to the enum names, nor explain the 'server-derived health' and 'role capabilities' as being part of the contract view rather than separate views. This creates some ambiguity.

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 ('Return') and clearly identifies the resource ('Project Mission') while enumerating the distinct view types (contract, goals, templates, scope-change, history). This sets it apart from siblings like get_project_context or get_project_activity, which cover different project aspects.

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

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

The description implies this is the tool for reading mission/goal stack data, but it does not explicitly state when to prefer it over alternatives or exclude other tools. The title reinforces the niche, but no direct comparison to sibling tools is provided.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds critical context: what is returned (policy, freshness, receipt, findings) and the important caveat that a pass never replaces human review. This goes beyond annotations and is not contradictory.

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

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

Two sentences with no fluff. The first sentence front-loads the action and output, the second adds a valuable caveat. 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?

The description enumerates return contents and includes a critical caveat, while annotations cover safety. With no output schema, the description does a good job of setting expectations. Missing edge-case behavior (e.g., no gate found) is a minor gap.

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

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

The schema fully documents assignment_id with format and pattern, but description coverage is 0%. The description's 'task-bound' hints at the parameter's role but does not explicitly explain it. For a single, self-named parameter, schema and name are sufficient.

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 'Return' and resource 'task-bound Quality Gate policy, freshness, deterministic check receipt, and attached findings.' It clearly distinguishes from the sibling 'run_task_quality_gate' by emphasizing retrieval of current state rather than execution.

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

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

Usage is implied through the read-only 'Return' and the 'task-bound' scoping, but there is no explicit 'use when' or alternative comparison. The human review caveat is a limitation, not a directive on when to use the 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 cover read-only and non-destructive behavior. The description adds valuable context beyond annotations, such as the fact that disabled shares return no URL and the notion of 'durable sharing state.' This provides additional behavioral clarity without contradicting any annotations.

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

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

The description is two short sentences, front-loaded with the core action and resource. No wasted words; every phrase adds meaning.

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

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

For a simple read-only tool with good annotations and a meaningful sibling set, the description is mostly complete. It covers the main return value (URL) and an edge case (disabled shares). However, the lack of any mention of the 'page' parameter and the absence of an output schema prevent a perfect score.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters, but it only mentions 'one exact saved version' implicitly mapping to version_id and project_id. The optional 'page' parameter is left completely unexplained, which is a significant gap given the low schema coverage.

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

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

The description states a specific action ('Read') on a specific resource ('durable sharing state and current URL for one exact saved version'), making the purpose unmistakable. It also distinguishes itself from sibling tools like create_version_share_link and revoke_version_share_link by focusing on retrieval.

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

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

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

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context by emphasizing 'immutable' and 'honestly labeled' signals, which tells agents that the receipt does not change and that the data distinguishes between observed and forecasted values. This goes beyond the annotation baseline.

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, which is concise, but it contains an awkward typo ('2ools-forecast' instead of 'tools-forecast') and the phrase 'honestly labeled worker-reported or 2ools-forecast context signal' is clunky. While not verbose, the odd wording reduces clarity and polish.

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

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

The tool is simple with one parameter, good annotations, and no output schema. The description lists the key returned components (receipt, lineage, signal) but does not explain their format or provide any usage example. For a read tool, it is adequate but leaves gaps about the expected output structure or how the lineage relates to the assignment_id.

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 only one parameter (assignment_id) with 0% description coverage. The description does not mention this parameter at all, nor does it explain how to find or use assignment_id. The parameter name is self-explanatory to some extent, but 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 clearly states the tool returns a specific resource: the current immutable context-handoff receipt, task lineage, and context signal. The verb 'Return' and the specific object distinguish it from other getter tools like get_project_context or get_task_quality_gate.

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

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

The description implies usage for retrieving handoff context but does not explicitly state when to use this tool over alternatives like prepare_work_handoff or get_project_context. There is no when/when-not guidance, though the context of 'current immutable' suggests it is for reading the latest handoff.

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 (idempotentHint=true, destructiveHint=false), the description discloses that the renewal does not widen the immutable step, time, or spend ceilings—an important behavioral trait for an agent deciding whether to call this tool. It also specifies that it operates on the authenticated worker's lease, adding auth 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, dense sentence that leads with the verb and packs in the key constraint about immutable ceilings. No wasted words or redundant 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 good annotations (idempotentHint, non-destructive) and a simple schema, the description conveys the core operation and its key restriction. It does not describe the return value or error handling, but the absence of an output schema and the low complexity make this acceptable for a renewal 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 0% description coverage, and the description does not elaborate on the parameters (session_id, used_steps, used_spend_cents). While parameter names and schema constraints convey some meaning, the optional usage counters are not explained—an agent cannot tell why they are needed or how they affect the renewal.

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 ('Renew') and the resource ('the authenticated worker's active lease'), and adds a distinguishing constraint: 'without widening its immutable step, time, or spend ceilings.' This separates it from sibling tools like submit_work_session, which likely creates a new lease.

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 renewing an active lease for the authenticated worker and that constraints are not changed. It provides clear context but does not explicitly mention alternatives or exclusions, such as 'do not use if you need to alter limits' or 'instead of submit_work_session.'

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 mark the tool as read-only and non-destructive. The description adds valuable behavioral detail: it returns project/version identity and attribution, never generated source, and filters to requests waiting for a delegated reviewer. This goes beyond the annotation hints and clarifies what the tool does and does not expose.

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 exactly two sentences, front-loaded with the action ('List exact saved versions...'), and each sentence provides distinct, useful information. No wasted words or redundancy.

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

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

For a list tool with simple optional parameters and no output schema, the description adequately covers the core behavior and return contents. It explains what is returned (identity/attribution, not generated source) and what the items are (waiting for a delegated reviewer). Some terms like 'exact saved versions' could be clearer, but overall it is sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific guidance; it does not explain the 'limit' or 'status' parameters, but the schema already fully describes them.

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

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

Description uses a specific verb ('List') and resource ('exact saved versions waiting for a separately delegated reviewer'), clearly distinguishing it from the sibling list_artifact_approval_requests by focusing on versions and attribution. It also specifies that it never returns generated source, eliminating ambiguity about output scope.

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

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

The description provides clear context for when to use the tool: when you need approval requests for exact saved versions awaiting a separately delegated reviewer. It does not explicitly name alternatives or exclusions, but the context is strong and the distinction from artifact-based approval requests is 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 read-only and non-destructive behavior. The description adds a useful auth requirement ('Requires separately delegated artifact review authority') and the 'exact' qualifier, providing context beyond what annotations offer.

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 tight sentences: one for purpose, one for a key prerequisite. No unnecessary words or repetition of schema or annotations.

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

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

For a simple read-only list tool, the description is adequate but leaves gaps: it doesn't explain the filtering semantics of status and project_id, and there is no output schema or return value description. The auth note adds context, but overall it could be more complete.

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

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

Schema description coverage is 0%, and the description does not mention the 'status' or 'project_id' parameters. The schema itself shows the enum and uuid, but the description adds no meaning about how these filter results or their 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 it lists exact artifact versions with a human review decision, using a specific verb and resource. It distinguishes itself from the sibling list_approval_requests by focusing on artifact versions and review decisions.

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 review requests, and the auth prerequisite is stated, but it does not explicitly mention alternatives or when-not-to-use scenarios. No exclusions are given, so usage guidance is implied rather than fully 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?

The annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: it lists only latest immutable versions and does not return stored bytes. This goes beyond annotation coverage, though it omits response format or pagination details.

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 wasted words. It front-loads the verb 'List' and packs in scope, behavior, and a key exclusion ('without returning stored bytes') efficiently.

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

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

Given the low complexity (one required parameter), strong annotations (readOnly, idempotent, non-destructive), and no output schema, the description is sufficiently complete. It clearly explains what is listed and the important behavioral caveat about not returning bytes.

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. While the schema itself is self-explanatory (name, type, format, pattern), the description provides no additional meaning or compensation for the low coverage.

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

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

The description uses a specific verb ('List') and resource ('durable project artifacts and each latest immutable version'), and explicitly states that it does not return stored bytes. This clearly distinguishes it from siblings like 'get_artifact' and other list 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 makes it clear that this tool returns metadata only ('without returning stored bytes'), implying when it should be used vs. when to fetch actual content. However, it does not explicitly name alternative tools or provide when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it applies to the 'paid account' and lists 'explicitly apply' capabilities, clarifying scope and authorization, which is useful 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?

Two sentences, front-loaded with the action, then usage guidance. No redundancy or filler.

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

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

The tool is simple with one optional param, rich annotations, and clear usage guidance. The description covers purpose, scope, and when to use, which is sufficient for a read-only list tool without an output schema.

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

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

The single parameter output_target is fully described in the schema (100% coverage), so the description doesn't need to add much. It reiterates the optional filtering behavior, but the schema already provides this, so a baseline 3 is appropriate.

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

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

The description clearly states the tool lists Curators, Rulebooks, and Skills for a paid account, using a specific verb and resource. It also differentiates from sibling build_from_conversation by positioning itself as the pre-step.

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 directs usage before build_from_conversation when a user names a creative system or asks what is available. It provides a clear use case and implies when not to use (e.g., when building directly).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing that the response contains only status and summary, not full Limits or run traces, which goes beyond the annotations.

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

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

Two sentences: the first states the action and scope, the second clarifies what is or is not included. Every word earns its place, with no wasted content or redundancy.

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

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

For a simple list operation with one parameter and no output schema, the description is sufficient. It explains what the tool returns (status/summary) and what it omits (full Limits/run traces), which is enough given the straightforward nature and good annotation coverage.

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 project_id already described as a 'Readable 2ools project ID.' The description reinforces the need for a readable project but adds no new parameter semantics beyond the schema. Baseline of 3 applies.

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

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

The description uses the specific verb 'List' with the resource 'built-in Agents assigned to one readable project,' clearly distinguishing it from sibling tools like get_agent (singular), list_projects (project list), or run_project_agent. The scope ('authorizing account', 'one readable project') is explicit.

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

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

The description notes 'This reveals status and summary, not full Limits or run traces,' which gives context about the level of detail returned. It implies when this tool is appropriate (lightweight status check) but does not explicitly name alternatives or exclusions, so a small deduction applies.

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

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

Annotations already convey readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context about 'page-anchored' feedback and 'explicit human or external-agent attribution', but does not describe return structure, pagination, or other behavioral details.

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, efficient sentence that front-loads the primary action and key qualifiers. No redundant wording or repetition of schema information.

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

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

For a simple read-only list tool with only two parameters and strong annotations, the description covers the essential purpose and unique context. However, without an output schema, it does not describe the return shape, though this is a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100%, with clear descriptions for both project_id and include_resolved. The description adds no additional parameter-level detail beyond what the schema already provides, so baseline 3 applies.

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

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

Provides a specific verb ('Read') and resource ('page-anchored review feedback for versions in a project'). Clearly distinguishes from sibling tools like add_project_feedback or resolve_project_feedback by indicating read-only intent and a unique 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?

Implies usage context as a read operation for feedback, and the name aligns with list semantics. However, it does not explicitly state when to use this over alternatives, such as when to use list_project_pins or resolve_project_feedback.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by specifying that the returned items are 'shared workspace notes and http(s) links, with explicit attribution'—giving insight into the nature of pins and the output's attribution detail beyond what annotations capture.

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

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

The description is a single, front-loaded sentence that immediately states the action and resource. Every word earns its place, with no fluff or redundancy. It is concise yet informative.

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

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

For a simple read-only tool with one parameter and strong annotations, the description covers the core purpose and scope. However, with no output schema, it lacks details about the return format, pagination, or ordering, and 'explicit attribution' is vague. Overall, it is adequate but not exhaustive.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not mention the sole parameter `project_id`. While the parameter name and schema format (uuid) are self-explanatory, the description adds no semantic value, leaving the agent to assume that `project_id` identifies the workspace/project whose pins 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 uses a clear verb ('Read') and resource ('shared workspace notes and http(s) links'), making it evident that this tool lists pins. It distinguishes from sibling tools like add_project_pin and remove_project_pin by focusing on read-only retrieval, though it does not explicitly contrast with them.

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

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

No guidance is provided on when to use this tool versus alternatives. The description simply states what it does, leaving the agent to infer usage from the tool name and annotations. Sibling tools such as list_project_feedback or add_project_pin are not mentioned, so there is no explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is clear. The description adds context about 'recent' projects and 'compact metadata without generated source', but does not detail pagination or return structure. No contradictions with annotations.

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

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

Two concise, front-loaded sentences. No redundant or irrelevant information. Every word adds value.

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

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

For a list tool with one parameter and no output schema, the description is fairly complete: it states what is listed, the access scope, and the output nature. It does not describe pagination or exact fields, but the limit parameter and annotations mitigate this. Slightly incomplete compared to the high benchmark.

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% as the single 'limit' parameter has a complete description. The description adds no additional parameter info beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states the verb ('List'), the resource ('recent 2ools projects'), and the scope ('the authenticated account can access, including owned and shared projects'). It also distinguishes from siblings like get_project or list_project_feedback by specifying 'compact metadata without generated source'.

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 clear context for when to use the tool (to list accessible projects), but does not explicitly mention alternatives or exclusions. The phrase 'including owned and shared projects' gives helpful scope, but lacks explicit 'instead of' guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the notion of 'durable' and the specific categories returned, which gives some context, but it does not disclose behaviors like pagination, ordering, or that status filtering is supported. 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, front-loaded sentence with no filler. Every phrase contributes to conveying the resource scope, making it appropriately concise.

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

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

Given the tool's simplicity, the robust annotations, and the schema showing the required project_id and optional status enum, the description is minimally adequate. However, there is no output schema and the description does not explain return format or behavior (e.g., whether results are sorted, paginated, or scoped to the project), so it is not fully complete.

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

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

Schema description coverage is 0%, and the description does not mention project_id or status at all. It provides no guidance on how parameters filter the result set, so the agent must rely entirely on the schema, which is insufficient given the low coverage.

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

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

The description uses a specific verb ('List') and resource ('project work assignments'), and further enumerates the scope as 'durable project work contracts, bounded attempts, leases, budgets, and result references.' This clearly distinguishes it from sibling tools that create, claim, or decide work assignments, as well as from list tools targeting other resources.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. There is no mention of when to choose list_work_assignments over create_work_assignment, claim_work_assignment, or other list-oriented siblings, leaving usage context entirely 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 signal idempotent and non-destructive behavior. The description adds meaningful behavioral specifics: self-acceptance of proposals is prohibited, and verifier definitions are purely descriptive and never execute arbitrary code. These are non-obvious constraints beyond the structured fields, and they don't contradict any annotations.

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

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

The description is compact at two sentences and front-loads the core actions. The second sentence adds useful governance context but is dense and contains a typo ('2ools'), which slightly reduces clarity. Overall, it earns its place without excessive verbiage.

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

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

This is a high-complexity tool with five distinct change types and no output schema. The description provides a useful high-level overview and policy reminders, but it doesn't explain prerequisites (e.g., project_id is required) or offer hints about constructing the change object. Given the rich schema, the description is a decent starting point but not a complete guide 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 carries a heavy burden. It maps the high-level actions (propose, version, attach) to the oneOf change variants, giving semantic scaffolding. However, it offers no field-level detail about project_id or the internal structure of the change object, leaving the agent to rely entirely on the schema for parameter meaning.

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

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

The description names three concrete verb-resource pairs: propose a project trade-off, version an eval case or verifier definition, and attach an eval/verifier receipt. It clearly situates the tool in the project-discipline domain and differentiates it from read-only siblings like get_project_discipline, though it doesn't enumerate the exact action constants such as propose_decision or save_eval_case.

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 recording discipline evidence but does not explicitly say when to prefer it over alternatives like add_project_feedback or manage_work_watchdog. It does supply practical governance constraints (agents cannot accept their own proposals; verifier definitions never execute code), which helps narrow appropriate use, but lacks explicit alternative guidance.

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

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

Annotations already convey idempotent/destructive hints. The description adds valuable boundary context: it never answers for the user, approves risky actions, deploys, spends, sends externally, deletes data, or widens authority. This goes beyond annotation fields and helps the agent understand safety/scope constraints.

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

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

Two sentences, no filler. The first sentence front-loads the primary actions, the second adds useful boundary conditions. Every word earns its place.

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

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

Given the complex oneOf schema, two required parameters, and no output schema, the description is incomplete. It does not describe return values, side effects, what 'park' vs 'pause' means, error behavior, or prerequisites. The high-level scope is present, but not enough 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 coverage is 0%, so the description must compensate. It vaguely maps to the 'change' parameter's actions (pause/park/resume/reprioritize/configure) but does not explain required fields like assignment_id, expected_revision, idempotency_key, or the configure policy structure. The description adds minimal value for 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 uses specific action verbs ('Pause, park, resume, or reprioritize', 'configure') tied to a clear resource ('one durable task', 'project Watchdog'), and distinguishes itself by listing excluded actions. This is a specific and differentiating purpose statement.

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 action list implies usage contexts, and the 'never' clause provides explicit exclusions (e.g., not for approving risky actions). However, it does not name sibling tools or give explicit 'when to use this instead' guidance, leaving usage to be inferred.

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

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

Annotations provide readOnlyHint=true and destructiveHint=false. The description adds that stored bytes never enter MCP model output, a privacy-relevant behavioral trait not inferable from annotations, plus the five-minute expiry. No contradiction; creating a URL is not a data mutation.

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, second sentence adds a key non-obvious trait (bytes never enter output). 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?

Tool is simple with 3 UUID params and no output schema. Annotations cover safety; description communicates purpose, expiry, and privacy guarantee. It doesn't explicitly state the response format (the URL itself), but that is strongly implied. Adequate for 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 0% and the description only mentions 'one immutable artifact version', mapping to artifact_version_id. project_id and artifact_id are left entirely to name inference; no detail is provided on relationships or lookup 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?

Description states 'Create a five-minute download URL for one immutable artifact version' – a specific verb (create) and resource (immutable artifact version). It distinguishes from siblings like prepare_artifact_upload and create_version_share_link via the five-minute expiry and immutable version focus.

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

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

No explicit when-to-use or alternative exclusions. The description implies usage for temporary downloads, but does not contrast with prepare_version_export or create_version_share_link despite their presence in sibling tools.

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

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

Beyond the annotations, the description discloses time-limited URL creation (five-minute), the exact-bytes requirement, and the policy that uploads never replace current artifacts before approval. It does not cover failure modes or return details, but adds meaningful behavioral context.

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

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

The description is two sentences, front-loaded with the core action and a key behavioral constraint. No redundant or filler wording exists.

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 10 parameters and no output schema, the description omits critical information such as the return value (the PUT URL), how to upload bytes to that URL, and error behavior. It covers only the high-level purpose and review policy, leaving substantial gaps for a complex tool.

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

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

Schema description coverage is only 20%, and the description does not explain the meaning of parameters like project_id, kind, byte_size, sha256, or the required vs optional artifact_id/parent_version_id. The phrase 'exact bytes' is too vague to guide parameter construction.

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: creating a five-minute PUT URL for exact bytes. It also distinguishes this tool from others by emphasizing the pending review and no-replacement behavior, which separates it from version upload/approval workflows.

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 that this tool is for external-agent output requiring review, implying when to use it. It does not explicitly name alternatives or state when not to use it, but the review-flow context gives sufficient guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is safe. The description adds valuable context beyond annotations: the URL is valid for five minutes, and the source is not embedded in MCP output. This clarifies output behavior and expiry, which annotations do not cover. 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?

Two short sentences, front-loaded with the main action. The second sentence adds critical distinctiveness (source delivery). No fluff, 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 tool with two UUID parameters, good annotations, and no output schema, the description covers the core purpose, the expiry behavior, and the output expectation (a URL via download route). It does not specify the exact response shape, but given the simplicity and annotations, the description is nearly complete.

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

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

With 0% schema description coverage, the description must compensate, but it only vaguely references an 'exact saved version' and does not elaborate on project_id or version_id. The parameter names are self-explanatory, but the description adds no detail about their relationship or how to obtain them. This is adequate but not strong.

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 a five-minute download URL) and the resource (an exact saved version), distinguishing it from siblings like prepare_artifact_download (which handles artifacts) and create_version_share_link (which likely creates a share link). The phrase 'exact saved version' and the expiry duration make the purpose 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 clear context: use this tool when you need a temporary download URL for a specific version. The second sentence ('Source is delivered by the download route, never embedded in MCP model output') gives an explicit when-not behavior—do not expect source content in MCP output. However, it does not explicitly name alternative tools or exclusions, so it stops short of full 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?

The description adds behavioral detail beyond annotations: it mentions 'immutable, exactly-once' and that estimated signals are labeled as estimates, and that questions/committed effects are paused. These align with the idempotentHint but enrich the safety and side-effect profile. 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 concise at two sentences with the main action front-loaded. However, the dense jargon ('successor envelope', 'owned session') makes it less accessible, though it earns its place by packing meaning into few words.

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

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

Given 7 parameters, no output schema, and no parameter descriptions, the description is insufficient for an agent to confidently invoke the tool. It lacks information about return values, prerequisites, or concrete examples of what a 'successor envelope' contains, making it incomplete for a nontrivial operation.

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 it only vaguely references 'estimated signals' (relating to signal_kind/label) and 'exactly-once' (relating to idempotency_key). It provides no meaning for required parameters session_id and idempotency_key, nor the other optional fields like reason, request_handoff, or remaining_context_tokens.

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 clear action ('Checkpoint one owned session into an immutable, exactly-once successor envelope') and the title clarifies it is about preparing a handoff. However, it does not explicitly differentiate from the sibling 'checkpoint_work_session' tool, and the metaphor of 'successor envelope' is vague.

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 'questions and possibly committed effects stay paused for a person' implies this tool is for pausing work for human review, which provides context for when to use it. Yet there is no explicit statement of when not to use it or which alternative tools (e.g., checkpoint_work_session) to prefer.

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?

It goes beyond the annotations by disclosing that the tool consumes one persisted project iteration, preserves the base as currentCode, and returns an asynchronous job_id. These are meaningful behavioral details not visible in annotations, and there is no contradiction with the given hints.

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 compact sentence that upfront states the action, then cleanly lists the core side effects and return type. It avoids verbose language and every phrase contributes meaningful information.

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

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

The description captures the essential contract: expected inputs, side effects (consuming an iteration, preserving base), and return format (async job_id). It does not spell out error handling or how to poll the job_id, but given the strong schema and annotations, this is a minor gap.

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

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

The input schema itself provides full coverage (100%) with descriptions for all five parameters, so the description does not need to compensate. It reinforces that feedback should be concrete but adds little new semantic detail beyond the schema.

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

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

The description uses a specific verb ('Create') and resource ('protected child version') with explicit inputs ('saved base version and concrete review feedback'). It clearly distinguishes this tool from sibling version approval/comparison tools by emphasizing the protected child version and iteration consumption.

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 intent to refine a saved base version using concrete feedback, but it does not explicitly state when to prefer this tool over alternatives nor provide when-not-to-use scenarios. The guidance remains implicit rather than direct.

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 redundantly restates this. It adds minor behavioral context (e.g., 'pending' and 'useful feedback') but does not disclose side effects or consequences of rejection beyond what the annotations cover. 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 short, front-loaded sentences with no filler. Every word adds value, and the main verb+object structure is immediately clear.

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 tool with no output schema, the description covers the core action and idempotency. However, it lacks information about post-rejection behavior, reversibility, or how it differs from the sibling 'reject_version', leaving some contextual gaps for an agent to infer.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'note' parameter indirectly via 'with useful feedback', and 'request_id' is self-explanatory given the tool's name. However, it does not provide explicit parameter-level details, and the description only partially fills the 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 uses a specific verb 'Reject' and clearly identifies the resource: 'one pending immutable artifact version'. It also adds useful scope constraints ('pending', 'immutable') and mentions the purpose of the action ('with useful feedback'), making it distinct from sibling tools like approve_artifact_version.

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

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

The description implies when to use the tool (i.e., for pending immutable artifact versions) but does not explicitly state when not to use it or name alternatives like reject_version. The usage context is clear enough but lacks explicit exclusions or alternative references.

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 details beyond what annotations already provide: if the version is active, its saved parent is restored as active, and the rejected version remains in immutable history. It also highlights the authority requirement. Annotations (destructiveHint: true, idempotentHint: true) are not contradicted.

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, directly states the action and key consequences, and contains no fluff or repetition. Every clause carries meaningful information, 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?

The description covers the primary operation, active-version behavior, immutability, and authority prerequisite. However, it does not state what happens if the version is not active, which is a notable gap. Since there is no output schema, it also does not clarify return values, but the core behavior is well covered.

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 having a clear description. The tool description adds no new parameter-level semantics; it does not mention the 'REJECT' confirmation const or the decision_note content beyond what the schema already states. 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: reject one saved version using separately delegated review authority. It also specifies key side effects: if the version is active, its parent is restored as active, and the rejected version remains in immutable history. This goes beyond a simple verb+resource and distinguishes it from generic 'reject' tools.

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

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

The description provides a precondition ('separately delegated review authority') but gives no explicit guidance on when to use this tool versus alternatives like reject_artifact_version. It does not mention exclusions or when not to use it, leaving the agent to infer the appropriate 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 destructiveHint=true and idempotentHint=true. The description adds no extra behavioral context beyond repeating 'idempotent', which is redundant. It does not disclose side effects, permission requirements, or what exactly gets removed.

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

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

Two short sentences with no excess wording. However, the second sentence merely repeats the annotation's idempotentHint, so it does not fully earn 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 destructive operation with two required parameters and no output schema, the description is critically sparse. It lacks parameter explanations, the relationship between the pin and project, and any operational context beyond removing a pin.

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

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

Schema description coverage is 0% and the description does not explain the meaning of project_id or pin_id. The agent cannot infer which UUID refers to what without additional context.

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 'Remove one shared workspace pin' – a specific verb ('Remove') and resource ('shared workspace pin'). It distinguishes from siblings like add_project_pin and list_project_pins.

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 remove a pin), but provides no explicit context, alternatives, or exclusions. It does not mention when to use this versus adding or listing 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?

Despite annotations already declaring readOnlyHint, idempotentHint, and destructiveHint false, the description adds substantial behavioral context: the card is interactive, returns 'protected preview and access-checked workspace links', and explicitly states it does not include source code. This gives the agent a clear picture of the tool's output and safety characteristics beyond the annotations.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds value: the first states what it does, the second gives usage guidance and return details. No filler or redundancy.

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

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

For a simple 2-parameter tool with strong annotations and no output schema, the description is complete. It covers the main action, usage context, and what is returned (protected preview, access-checked links) and what is not (source code). No significant gaps remain.

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

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

The input schema already provides 100% coverage with descriptions for both project_id ('Project containing the saved version') and version_id ('Saved version to display'). The description adds no additional parameter-level semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Render an interactive, read-only card for one saved 2ools version.' It clearly distinguishes this from siblings like create_public_preview or create_version_share_link by emphasizing the read-only, interactive card nature and the exclusion of 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 provides explicit usage context: 'Use after get_build or get_project when the user wants to see, open, or share the result.' This clearly indicates when to invoke the tool, though it does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is known. The description adds the specific dual behavior of resolving or reopening, plus the owner-only permission requirement, which is useful beyond the annotations.

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

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

The description is a single, front-loaded sentence that conveys the key information without redundancy. It is 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 three-parameter tool with no output schema, the description is adequate but has a clear gap: it does not explain the 'resolved' parameter semantics or the consequences of each state. Annotations cover the destructive/idempotent aspects, but the description could be richer for full 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?

The schema has 0% description coverage, so the description must compensate, but it fails to explain the meaning of the 'resolved' boolean parameter, which directly controls whether the action resolves or reopens. It also does not elaborate on project_id or feedback_id roles beyond the obvious context.

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 clear, specific verb phrase ('resolves or reopens') and identifies the resource ('one saved feedback item'). The 'Owner-only' qualifier further clarifies the tool's scope and differentiates 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 'Owner-only review decision' clause clearly indicates this tool is for owners making a decision about saved feedback, which provides context on when to use it. However, it does not explicitly mention alternatives or when not to use it, so it falls short of full 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 adds useful context beyond annotations by mentioning 'immutable' revisions and 'server-gated' authority. It does not, however, explain what a restore operation does to the current state or how the completion review is processed, leaving significant behavioral gaps.

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-loading the key actions with no redundancy or filler. Every word serves a purpose.

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

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

Given the complexity of 5 distinct action types with many nested parameters and no output schema, the description is far too terse. It does not guide the agent on choosing between restore_mission, restore_goal, and restore_stack, nor does it clarify expected outputs or 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 0%, and the description provides no parameter-level details. While the schema's oneOf structure and required fields are explicit, the semantics of fields like expected_revision, restore_revision, and criteria_results are not explained anywhere in the description.

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

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

The description clearly enumerates the tool's functions: restoring Mission or Goal revisions, deciding scope changes, and submitting completion reviews. This distinguishes it from siblings like update_project_mission and get_project_mission, though the title's 'Review' is less precise.

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

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

Usage is implied by listing the supported actions, which tells an agent when to invoke the tool. However, there is no explicit contrast with alternatives (e.g., use update_project_mission for editing) and no exclusion criteria. The 'server-gated' note is about authorization, not usage context.

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

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

Annotations already flag destructive and idempotent behavior. The description adds valuable context by specifying that ALL public and code-protected URLs are disabled for the version, and clarifies the effect of re-publishing a protected link. This goes beyond the annotations.

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

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

Two sentences, front-loaded with the action, and the second sentence adds useful behavioral nuance. No wasted words or redundant structure.

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

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

The core behavior is clear and the annotations cover the destructive/idempotent profile. However, the complete lack of parameter explanations (especially idempotency_key) and no mention of return values or edge cases leaves gaps for an agent fully understanding the tool's invocation context.

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

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

Schema description coverage is 0%, so the description must compensate. It only hints at version_id via 'one exact saved version'; project_id and idempotency_key are entirely unexplained. This is a significant gap for correct invocation.

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

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

The description uses a specific verb 'Disable' and clearly identifies the resource: 'every existing public or code-protected URL for one exact saved version.' It directly contrasts with sibling tools like create_version_share_link and get_version_share_link, making its purpose unambiguous.

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

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

The usage context is implied (use this to revoke all share links for a version), but there is no explicit 'when to use' or 'when not to use' guidance. The note about re-publishing rotating codes hints at an alternative workflow, but it is not stated as a directive or exclusion.

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

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

Adds behavioral context beyond annotations: execution is queued, server-side enforces immutable Limits, project access, account fuse, and online Engine requirement, and a job only exists if these pass. This is valuable for understanding side effects. 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?

Two dense sentences with no filler; the first sentence states purpose and preconditions, the second details server-side enforcement.

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, combined with rich schema descriptions and annotations, is sufficient for selecting and invoking the tool. It would benefit from a word on return value, but the core purpose and constraints are fully covered.

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% parameter coverage with clear descriptions, so the description does not need to add parameter details. The main description's mention of immutable Limits indirectly reinforces the task parameter's constraint but adds little new beyond the schema.

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

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

The description uses a specific verb ('Queue real execution') and identifies the resource (project-linked Agent) with a key precondition (already test-ran and armed). It clearly differentiates from sibling tools like get_agent or cancel_agent_run by focusing on initiating an actual run.

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?

States the tool is for real execution of an Agent that was already test-ran and armed, implying you should use it only after those steps. It does not explicitly name alternatives or exclusions, but the context is unambiguous.

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 mark this as non-read-only, non-destructive, and idempotent. The description adds a meaningful behavioral guarantee: 'Missing routes, stale proof, failed checks, and open findings cannot become a false pass,' plus the constraint of 'same-project evidence.' This gives the agent insight into the tool's integrity enforcement beyond the static 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 entire description is two concise sentences with no redundant phrases. It front-loads the two actions and packs all key concepts—fingerprints, evidence, findings, and the no-false-pass guarantee—into a compact form.

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

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

The tool has a complex oneOf schema with two distinct modes (begin/complete), but the description does not disclose the required sequencing—that begin generates a run_id which complete must reference. It also doesn't mention any return values or error conditions, leaving out critical workflow steps for such a high-complexity 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?

With 0% schema description coverage, the description provides the only semantic mapping. It connects 'fingerprints' to artifact_fingerprint and environment_fingerprint, 'every configured check' to check_results, 'explicit findings' to findings, and 'same-project evidence' to evidence_refs. However, it does not explain the action discriminator, run_id, idempotency_key, or route_fingerprint, leaving 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 opens with two concrete verbs—'Start checks' and 'submit every configured check'—and explicitly names the target objects: 'exact task/artifact/environment fingerprints.' This clearly distinguishes run_task_quality_gate from the sibling get_task_quality_gate, which is a read operation, while this tool actively runs and settles the gate.

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 statement about when to use this tool versus siblings or when to choose the 'begin' vs 'complete' mode. The workflow is implied by the two modes but not explicitly guided; the agent must infer that begin is for starting checks and complete is for submitting results. The description does not mention alternatives like get_task_quality_gate.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description doesn't need to repeat those. It adds useful context that the call ends a lease and that results go to a separate review decision. However, it does not describe side effects like what happens if the lease is already ended, whether submission is final, or whether the idempotency_key prevents duplicate submissions.

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 main action, and contains no fluff. Every word contributes to understanding the tool's core behavior and flow.

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 six parameters, three required, and no output schema, the description is under-specified. It omits explanation of required fields like result_summary and idempotency_key, does not mention optional usage/spend fields, and provides no information about return values or workflow consequences beyond 'separate review decision'.

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 0% description coverage for six parameters, so the description carries the full burden. It only hints at 'typed result references' (likely output_refs) and 'lease' (session_id). It does not explain result_summary, idempotency_key, used_steps, or used_spend_cents, leaving the agent to guess their meanings and constraints.

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 two specific actions: ending the authenticated worker's lease and submitting typed result references for a separate review decision. This distinguishes it from siblings like heartbeat_work_session (which extends a lease) and claim_work_assignment (which starts work).

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 used when the worker is finished and wants to terminate the lease and hand off results. It mentions 'End the authenticated worker's lease' as a concrete trigger condition, and 'for a separate review decision' clarifies that the review is not part of this call. However, it does not explicitly list alternatives or exclusions (e.g., use heartbeat_work_session to keep the lease alive).

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 useful behavioral context beyond the annotations: it mutates the plan, operates only on the current conversation, returns the refreshed plan/timeline, and cannot mark work complete. However, it omits the 'steer' and 'decide_suggestion' actions, and does not mention constraints like idempotency keys or dependency-cycle rejection, leaving significant behavioral gaps.

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 tightly written in two sentences, with the core operations front-loaded and a precise limitation in the second sentence. There is no filler or redundant information.

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

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

For a tool with this complexity—six distinct change actions, idempotency keys, dependency constraints, and no output schema—the description gives only a high-level overview plus one key limitation. It mentions the return value but omits the existence of 'steer' and 'decide_suggestion' actions, making it incomplete for an agent to fully understand the tool's capabilities.

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

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

The description provides almost no parameter-level guidance, not explaining the project_id or the complex change structure with its six action variants. With schema description coverage at 50%, the description fails to compensate for missing explanations such as lane semantics, dependency replacement behavior, or idempotency_key requirements.

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

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

The description identifies the tool as updating a project's Living Plan by adding, editing, moving, or reordering items and returning the refreshed inline plan and timeline panel. It also distinguishes from completion tools by explicitly stating it cannot mark work complete. However, it omits the 'steer' and 'decide_suggestion' actions that are part of the schema, making the purpose not fully exhaustive.

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 specifies the use case: modifying open Living Plan items from the current conversation. It explicitly states a key non-use case—cannot mark returned work complete—implying that completion is handled by a separate tool. It does not name specific sibling tools or provide broader contextual guidance, but the exclusion is 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?

Annotations already indicate non-read-only, non-destructive, and idempotent. The description adds that server role, revision, conflict, and safety policy remain authoritative, which tells the agent that server-side rules may override client assumptions. This is useful context beyond the annotations.

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

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

The description is two sentences with no wasted words. It front-loads the core actions (create, revise, transition, reorder, propose) and adds a concise note about server authority.

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

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

Given the tool's complexity (seven action variants, nested objects, no output schema), the description is too minimal. It omits critical details about return behavior, error handling, and the purpose of revision/conflict fields. The server-authority note helps but does not cover the full scope.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter explanations. It summarizes the action types (write_mission, create_goal, etc.) but does not explain key fields like expected_revision, idempotency_key, or confirm flags. For a complex nested schema, this 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 specifies the tool's purpose: authoring mission and goal contracts, transitioning or reordering goals, and proposing scope changes. This distinguishes it from sibling tools like get_project_mission or review_project_mission, which are read/review 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 provides clear context for when to use the tool: whenever creating, revising, transitioning, reordering, or proposing changes to mission/goal state. It does not explicitly list alternatives or exclusions, but the usage context is unmistakable.

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 bar for additional disclosure is lower. The description adds useful behavioral details: events are returned oldest-first, and the cursor-advancement is skipped when resync_required is true. It does not enumerate response fields, but the key non-obvious behaviors are covered.

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

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

Three sentences with no fluff. The first sentence states the core action and constraint, the second explains ordering and use case, and the third provides a crucial conditional alternative. Every sentence earns its place.

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

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

Given that there is no output schema, the description does a good job explaining ordering guarantees, the timeout behavior, and the resync fallback to get_project_activity. It could still enumerate the expected response fields (e.g., events, next_cursor, resync_required, timed_out), but the provided information is sufficient for an agent to handle the cursor logic 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 each parameter already described (e.g., after_cursor as 'head_cursor from get_project_activity or next_cursor from a prior wait'). The description's mention of 'head_cursor or prior next_cursor' and 'up to 20 seconds' largely echoes the schema, adding no significant new parameter-level meaning. This is the baseline for high schema coverage.

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

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

The description clearly states the verb 'wait' plus the resource 'project activity' with specific constraints: new events newer than a head_cursor or prior next_cursor, with a 20-second timeout. This distinguishes it from sibling tools by emphasizing the blocking/polling behavior rather than a one-time fetch.

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

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

It explicitly says 'If resync_required is true, paginate get_project_activity instead of advancing the cursor,' naming the alternative tool and a specific condition to switch. It also implies the intended use case: 'so an outside agent can process them in order,' giving clear usage context.

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