Milestone

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds the crucial behavioral gate — that a human approval must precede the call — which is real context beyond the annotations. It does not, however, describe what is actually mutated or whether the change is reversible, so with annotations carrying the safety profile this is a solid but not rich 3.

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?

Four tight sentences, all load-bearing, with the action front-loaded and the precondition/anti-misuse warning following in logical order. No filler or repetition.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description supplies the approval precondition and the applicability examples, leaving only the mutation consequences unstated — a minor gap for a three-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies the meaning of `confirmed` ('Pass confirmed true only then'), which is useful, but says nothing about `changeId` or `milestoneSetId` beyond the schema's own uuid/ref typing. Partial compensation justifies 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?

States a specific verb+resource ('Apply one suggested milestone change') and clarifies the scope with concrete examples (extra deliverable, new acceptance criterion, new saved work). It implicitly routes away from the sibling suggest_milestone_change by framing this as the 'apply' side, though it never names that sibling explicitly.

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?

Gives an explicit precondition ('after the freelancer explicitly approves that change. Pass confirmed true only then') and a clear when-not ('Calling it is not a substitute for the freelancer's approval'). An agent knows exactly when this is appropriate versus the suggest_* sibling.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description usefully adds that approving a draft 'is not a commitment,' clarifying the softness of the action, but says nothing about auth requirements, reversibility, or who may call it.

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 short sentences, front-loaded with the action and then the guard condition. Every sentence carries information; no 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?

An output schema exists, so return values need no explanation. For a two-parameter mutation with annotations covering the safety profile, the description covers the key guard condition adequately, though the milestoneSetId reference is 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 0%, so the description must compensate. It explains the meaning of confirmed (only true after explicit freelancer approval), which is genuine added value beyond the schema's const true, but milestoneSetId is left entirely 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?

States a specific verb+resource: approving draft milestone definitions and acceptance criteria. It is distinguishable from siblings like define_milestone or save_acceptance_criterion, though it never explicitly names or contrasts 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?

Gives a real precondition — pass confirmed=true only after the freelancer explicitly approves — but frames it around parameter use rather than tool selection. No alternatives (accept_milestone_change, define_milestone) or when-not-to-use guidance is offered.

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 the safety profile (destructiveHint=true, idempotentHint=true), and the description adds genuinely new behavior the annotations cannot convey: a hard guard that rejects the call unless approval and criterion-completion preconditions hold, plus the warning that a refusal must not be reported to the client as completion. It omits what state the declaration itself mutates or how refusal surfaces.

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 short sentences, front-loaded with the action, then the guard, then the agent-facing consequence. No filler, and the most important constraint (the refusal) appears before the warning about it.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile while the description covers gating and error handling. The remaining gap is parameter identification, which neither schema nor description resolves for the two UUIDs.

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

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

Schema description coverage is 0%, so the description carries the full burden for two UUID parameters, yet it never names milestoneId or milestoneSetId nor clarifies which identifier scopes the lookup. It only refers to 'milestones' and 'that milestone' generically, leaving an agent to guess which UUID is which.

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?

States a specific verb and resource ('State that a milestone is complete'), and the refusal preconditions (milestones approved, all acceptance criteria met) implicitly separate it from siblings like mark_work_done or approve_milestones. It does not explicitly name a sibling, so the differentiation is inferential rather than stated.

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 refusal conditions function as explicit preconditions: only call this once milestones are approved and every saved acceptance criterion is met. The third sentence gives downstream behavioral guidance about not relaying completion to the client on refusal. No alternative tool is named for the states where this one refuses.

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

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

Annotations already declare the safety profile (destructive, idempotent, non-read-only), and the description adds behavior not visible there: the tool refuses under stated conditions and the agent must not tell the client the payment is released when that happens. It stops short of explaining what side effects a successful call has on client-facing wording.

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, front-loaded with the action, then the refusal conditions, then the reporting guard. Each sentence earns its place, though the refusal-precondition list is dense and could be split for readability.

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?

An output schema exists so return values need not be explained, and the annotations cover the mutation safety profile. What an agent needs in order to call this correctly and avoid misreporting the result is present.

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% for two required parameters, so the description carries the full burden and fails to meet it. 'milestone' is implied by the prose, but milestoneSetId is never mentioned and the odd $ref reuse for milestoneId is not clarified anywhere.

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?

States a specific verb and resource ('State that the next payment for a milestone is released'), which an agent can distinguish from nearby siblings like declare_milestone_complete or approve_milestones. It does not explicitly name a sibling it is not, so it stops short of full differentiation.

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

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

The description gives concrete preconditions that determine when the call will succeed (milestones approved, every saved acceptance criterion met, milestone complete), which is stronger than mere implied usage. It does not, however, name an alternative tool to use when those conditions fail.

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 this is a non-read-only, non-idempotent, non-destructive, closed-world write. The description adds real behavioral context beyond that: the draft-set state requirement and the hard refusal once milestones are approved, which is exactly the kind of state gating an agent cannot infer from annotations. It omits auth/permission requirements and what happens to an existing set's other data, keeping it from a 5.

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 payload, followed by the gating rule. Every clause carries information; no filler or restatement of the 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?

An output schema exists, so return values need not be explained, and the description covers the critical workflow gate that governs success/failure. The remaining gap is the undocumented milestoneSetId parameter and its relationship to open_milestone_set/list_milestone_sets.

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 carry the parameter burden. It names and explains two of the three parameters (title, definition) but never mentions milestoneSetId or the maxLength/minLength constraints, so it only marginally compensates for the coverage 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?

States a specific verb and resource ("Add one milestone") plus the scope ("to a draft set") and the payload (title and definition). An agent can distinguish it from suggest_milestone_change or accept_milestone_change without opening any schema.

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?

Gives an explicit when-not rule: after milestones are approved a new milestone is refused, and the alternative is accept_milestone_change applying an add_milestone suggestion. It does not, however, contrast against suggest_milestone_change for the unapproved-case workflow, so routing in the normal case is left partly 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds a real behavioral constraint (results are limited to the authenticated freelancer's sets, and ids must come from this call rather than being invented), but it says nothing about the offset pagination behavior implied by the schema.

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

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

Three short sentences, front-loaded with what the tool returns and followed immediately by the action the agent should take next. No filler or restatement of the title.

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?

Low-complexity read tool with an output schema, so return-value detail is unnecessary, and the description supplies the workflow linkage to read_milestone_set. Only the optional offset/pagination semantics are left 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?

There is one parameter (offset) with 0% schema description coverage and the description never mentions pagination, page size, or how to advance through results. With the schema providing only a bare integer bound, the description fails to compensate for the documentation 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?

States a specific verb and resource ("List ... milestone sets") and narrows scope to the signed-in freelancer's own sets. It also implicitly distinguishes itself from the sibling read_milestone_set by framing this as the discovery step that produces the id read_milestone_set consumes.

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 routes the agent onward: "Use a returned id with read_milestone_set" and warns "Do not guess a set." That is clear when-to-use and when-not guidance, though it never states the inverse case (e.g., if you already have an id, skip 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 readOnly=false, idempotent=true, destructive=true, and openWorld=false, so the safety profile is largely covered. The description does add one real behavioral fact not present in annotations: the tool refuses when the target was never saved. It says nothing about the effects of the destructive state change or repeat-call behavior implied by idempotentHint, so it is only marginally additive.

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 short sentences, front-loaded with the core action. The last two sentences ('Refuses when the work item was not saved' / 'Do not mark unsaved work done') restate the same precondition in negative imperative form, a small redundancy that keeps it out of the top band.

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?

An output schema exists, so return values need not be explained, and the precondition coverage is helpful. But for a three-parameter mutation tool with 0% schema coverage and alias-typed ids, the description omits any parameter or workflow detail (e.g., that save_work_item precedes this call), leaving a notable gap for an agent trying to invoke it correctly.

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

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

All three parameters (milestoneSetId, milestoneId, workItemId) carry 0% schema description coverage, and the schema defines two of them via $ref aliases with no format or meaning stated. The description mentions none of them, so an agent gets no help understanding which identifiers are required or how they relate.

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?

States a specific verb and resource ('mark one saved work item done') with clear scope ('one'), so the agent knows this is a single-item state change rather than a bulk operation. It does not explicitly distinguish itself from nearby siblings like declare_milestone_complete or save_work_item, so it stops short of a 5.

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

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

The description gives a when-not condition ('Refuses when the work item was not saved. Do not mark unsaved work done'), which is genuine guidance beyond the schema. However, it never names the alternative action (e.g., save_work_item first) nor states when this tool is preferred over the milestone-level completion tools, leaving the agent to infer the workflow.

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 this as a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds genuine behavioral context by clarifying the draft is not an approved commitment until approve_milestones, which is a meaningful lifecycle trait not present in annotations or schema.

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

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

Two short sentences with the core action front-loaded and the lifecycle caveat second; nothing is redundant or padded. 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?

An output schema exists, so return values need not be explained, and annotations cover safety. But for a write tool with three undocumented, schema-coverage-0% parameters, the description should clarify at least the role of 'reference'; the parameter gap leaves an agent under-informed.

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

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

Schema description coverage is 0%, so the description carries the full burden for three required parameters. It only vaguely implies clientName and projectTitle via 'one client project' and says nothing about the 'reference' string or the formats/constraints of any field.

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?

States a concrete verb and resource ('Open a draft milestone set for one client project') and distinguishes the draft state from an approved commitment. It does not fully differentiate itself from siblings like define_milestone or list_milestone_sets, and the verb 'open' is slightly ambiguous versus a plain create.

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

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

It points to approve_milestones as the step that turns drafts into commitments, giving implied workflow context. However, it never states when to call this versus define_milestone, save_acceptance_criterion, or list/read variants, so the agent must infer placement in the flow.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description goes further by disclosing authorization semantics ('Proposed changes are not authorization') and interpretation rules for the returned data (don't claim completion unless complete is true, don't claim payment release unless paymentReleased is true), which is real added context beyond the structured fields.

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 leading instruction is well front-loaded, but the body devolves into a run-on sequence of prohibitions with an awkward mid-sentence clause about mayTellClient/clientWording. Each rule carries meaning, but the ordering and flow could be tightened.

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 an output schema present, the description needn't document return values, yet it usefully names key fields (complete, paymentReleased, mayTellClient, clientWording), which helps interpretation. The only substantive gap is the undocumented input parameter, which for a single required UUID is minor.

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

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

Schema description coverage is 0% and the single milestoneSetId parameter is undocumented in both schema and description. The description never explains what the ID refers to or where to obtain it, so it fails to compensate for the coverage 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 states a specific verb and resource ('Read the milestone set') and positions the tool within a workflow ('before answering'), which is clear. However, it does not distinguish itself from close siblings like list_milestone_sets or open_milestone_set, so an agent must infer the distinction from the ID parameter.

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?

'Read the milestone set before answering' implies a workflow ordering and a trigger condition, giving usable context. But it names no alternatives and gives no when-not guidance relative to the sibling read/list tools, leaving selection guidance 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 give readOnlyHint=false, idempotentHint=true, destructiveHint=false, so safety and idempotency are covered structurally. The description adds real behavioral context: this is a partial record that does NOT complete the milestone or release payment, which is exactly the non-obvious trait an agent could misread.

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 short sentences, zero waste, with the core action front-loaded and the disclaimers following immediately.

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?

An output schema exists, so return values needn't be explained, and annotations cover the safety profile. But with 0% param coverage and no hint at the param hierarchy or which identifiers are required, the definition leaves an agent guessing at how to populate the three UUIDs.

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% and the description names no parameters at all; the three UUID params (milestoneSetId, milestoneId, criterionId) and their hierarchical relationship are only inferable from the schema's $ref nesting. The description does not compensate for the coverage 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?

Specific verb+resource: 'Record that one saved acceptance criterion was met.' It precisely names the grain (one criterion) and the precondition (must already be saved), distinguishing it from siblings like save_acceptance_criterion and declare_milestone_complete.

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 precondition (criterion must already be saved) and clarifies scope, but never names the alternative tool for the 'next step' it disclaims. An agent knows when it can call this, but not explicitly which sibling to call when the case doesn't fit.

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

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

Annotations only state the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description adds the state-dependent refusal rule that annotations cannot express, plus an explicit scope boundary against completion marking. It does not address the non-idempotent hint (whether saving the same statement twice duplicates criteria), leaving one behavioral question open.

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 tight sentences with no filler, and the core definition is front-loaded ahead of the constraint. The middle sentence ('refused until an accepted add_criterion suggestion') is compressed enough to require a re-read, which keeps it just short of ideal.

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?

An output schema exists, so return values need no explanation, and the state guard plus scope boundary are covered. What remains missing is any parameter guidance and any statement about duplicate saves on a non-idempotent write, which is a noticeable gap for a three-required-param mutation 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 0% and the description never mentions the three required parameters (milestoneSetId, milestoneId, statement), not even the 500-character statement limit or its expected content. With zero schema-side documentation and no compensating prose, an agent must infer all parameter meaning from 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?

Names a specific verb and resource ('Save one acceptance criterion') and immediately defines the domain meaning ('what done means for that milestone'), which lets an agent separate it from record_criterion_met or declare_milestone_complete. The closing clause explicitly rules out a sibling's behavior: 'This does not mark the milestone complete.'

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?

Gives a real usage condition and a when-not: after milestones are approved, new criteria are refused until an accepted add_criterion suggestion. It does not, however, route the agent between this tool and alternatives like save_deliverable or suggest_milestone_change, so it stops short of full when/when-not coverage.

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

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

Annotations only declare the generic write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false); the description adds the state-dependent refusal rule tied to milestone approval, which is genuinely new behavioral context. The closing warning about not inventing unsaved deliverables is also non-obvious, though permissions and side effects remain unstated.

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 short sentences, front-loaded with the core action before the conditional rule. The final warning sentence is slightly cryptic but still earns its place as a guard against fabricating records.

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?

An output schema exists, so return values need no explanation, and the approval-gated refusal rule covers the main behavioral surprise. The gap is parameter documentation: with 0% schema coverage, an agent gets no guidance on the UUID/string formats or length limits of the four required inputs.

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% across all four required parameters, so the schema contributes no semantics. The description mentions none of milestoneSetId, milestoneId, title, or detail by name or format, adding only a weak hint that a milestone linkage exists. It fails to compensate for the coverage 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?

States a specific verb and resource ('Save one deliverable') and scopes it ('belongs to a milestone'), which implicitly separates it from siblings like save_work_item and save_acceptance_criterion. It never names an alternative explicitly, so it stops short of full sibling differentiation.

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

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

The description supplies a real precondition (extra deliverables are refused after milestone approval until an accepted add_deliverable suggestion) which tells the agent when the call will fail. However it never states when to use save_deliverable versus save_work_item or save_acceptance_criterion, and no alternatives are named.

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 cover the operation profile (mutation, non-idempotent, non-destructive, closed-world), and the description adds non-obvious lifecycle constraints beyond them: post-approval refusals and the dependency on an accepted add_work_item suggestion. It omits any note on validation limits or error behavior, keeping it from a 5.

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 short sentences, front-loaded with the core action and purpose, and every sentence carries a distinct constraint. No filler or repetition.

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

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

An output schema exists, so return values need not be described, and annotations cover safety. However, with 0% parameter schema coverage and no explanation of the two ID fields, the definition leaves a real gap for an agent that must decide what to supply.

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% for all three parameters. The description hints at the milestone linkage ('under a milestone') and the payload ('one piece of work'), but never explains what milestoneId versus milestoneSetId mean or how they relate, so it does not compensate for the schema 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 states a specific verb+resource ('save one piece of work under a milestone') and clarifies the downstream purpose ('so it can later be marked done'), which distinguishes it from the sibling mark_work_done. It doesn't explicitly name a sibling as an alternative, so it falls short of a 5.

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

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

It gives a concrete precondition chain: work must be saved before it can be marked done, and after milestone approval new work is refused until an accepted add_work_item suggestion. That is real when-to-use guidance, though it stops short of naming explicit alternatives for saving versus defining.

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 the safety profile (destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description still adds genuinely useful context beyond the annotations by clarifying that recording succeeds as a suggestion without mutating the underlying milestones.

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?

Front-loaded with purpose then the key behavioral caveat, followed by a tight per-kind requirement list. Dense and free of filler, though the terse 'Record a suggested change' opener is slightly thin for an opener.

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?

An output schema exists, so return values need no explanation. For a 9-parameter tool with conditional requirements, the per-kind field mapping covers the hardest part; only the meaning of the two always-required fields goes unexplained.

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, and it does the most valuable part: mapping each 'kind' enum value to its conditionally-required fields (e.g. add_criterion needs milestoneId and statement). It leaves the required milestoneSetId and summary undocumented, but the conditional mapping is a strong, non-obvious addition over the bare 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?

States a specific verb+resource ('Record a suggested change') and immediately distinguishes it from the actual mutation by noting 'This does not change the milestones.' This implicitly separates it from the sibling accept_milestone_change, though no sibling is named explicitly.

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: this is a suggestion-recording tool rather than one that applies changes, and 'does not change the milestones' gestures at that boundary. But it never names alternatives like accept_milestone_change or approve_milestones, nor states when a suggestion should be filed instead of making a real change.

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

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

Annotations only declare non-readonly, non-idempotent, non-destructive. The description adds substantive behavior: the wording becomes locked after approval and further variation is refused until a revision suggestion is accepted. That lock-in/refusal behavior is not derivable from annotations and is exactly the context an agent needs.

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, front-loaded with the core action, then the lock constraint, then the boundary on scope. No filler; slightly dense but every clause carries 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?

An output schema exists, so return values need not be described. The description covers the mutation's lifecycle constraint and the fact-source boundary, which are the main ambiguities for a 2-param write tool. Minor gap: no mention of what happens on rejection or validation failure.

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% for two required params (milestoneSetId uuid, wording string 1-2000 chars), so the description must compensate. It conveys what 'wording' semantically represents but adds no format, scope, or length guidance and says nothing about milestoneSetId. It partially compensates, not fully.

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

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

States a specific verb ('Record') and resource (client-facing wording about milestones, completion, payment release), which is distinguishable from siblings like define_milestone or approve_milestones. It does not explicitly name a sibling it replaces, but the resource is narrow enough for an agent to route correctly.

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?

Gives a concrete precondition/constraint: after approval, differing wording is refused until an accepted revise_client_wording suggestion, and the assistant must not exceed this wording plus facts from read_milestone_set. It does not cover all alternatives among the 15 siblings, but the when-not condition is explicit.

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