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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds the useful nuance that a draft is not a commitment, clarifying the state transition, but says nothing about what the approval overwrites, whether it can be undone, or the idempotent behavior. With annotations carrying the safety burden, a 3 is appropriate.

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

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

Three short sentences, zero filler, with the core action and its precondition front-loaded. Every sentence carries distinct 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?

An output schema exists, so return values need no explanation. For a destructive, idempotent state-change tool the description covers the gating condition adequately, though it could say more about reversibility and what the approval commits the freelancer to.

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

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

Schema description coverage is 0%, so the description must compensate. It does for the critical confirmed parameter, explaining the exact gating semantics (only true after explicit freelancer approval) beyond the schema's bare const:true. milestoneSetId is left to its self-evident name, which is a minor 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 (approve) and resource (draft milestone definitions and acceptance criteria), which is clear against siblings like define_milestone or save_acceptance_criterion. It stops short of naming an alternative tool or distinguishing itself from accept_milestone_change, so sibling differentiation is implied rather than 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?

Gives a concrete precondition for invocation: only pass confirmed true after the freelancer explicitly approves. That is a real when-to-use rule. It does not name an alternative tool or state when not to use this one, so it falls short of a 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?

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 destructiveHint=true and non-idempotent, but the description goes beyond them by disclosing a lifecycle gate: new milestones are refused post-approval until a suggestion is applied. It does not explain what makes the write destructive or whether repeated calls create duplicates, so the disclosure is strong but not exhaustive.

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

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

Two sentences, zero filler, with the core action front-loaded and the lifecycle constraint following immediately. Every clause carries information an agent needs.

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-machine behavior is well covered. The remaining gaps are the undocumented milestoneSetId and how a set reaches draft status, which are minor for a three-parameter add 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 names two of the three parameters ('a title and the definition of that milestone'), clarifying the semantic split between title and definition, but it never mentions milestoneSetId or the length constraints, leaving the call-shaping parameter undocumented.

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 a specific verb and resource ('Add one milestone to a draft set') and immediately scopes it to draft sets, which cleanly separates it from approve_milestones and accept_milestone_change in the sibling list. An agent can identify the operation and its target state without opening the 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?

It states the condition under which the call succeeds (a draft set), the condition under which it is refused (after milestones are approved), and the remediation path (accept_milestone_change applying an add_milestone suggestion). When-to-use, when-not-to-use, and the alternative route are all explicit rather than 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 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 already declare readOnlyHint=false, idempotentHint=true and destructiveHint=true, so the safety profile is covered. The description adds real value beyond that: a precondition (criterion must pre-exist) and an explicit statement of what the call does NOT trigger, which is the key behavioral ambiguity for this 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?

Three short sentences, front-loaded with the action, then the precondition, then the effect boundary. No filler; every sentence carries 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?

An output schema exists so return values need no explanation, and the description covers purpose, precondition and effect limits for a mutation tool. The remaining gap is parameter meaning, which is undocumented in both the description and the schema.

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

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

Schema description coverage is 0% and the description explains none of the three UUID parameters. 'one saved acceptance criterion' loosely implies criterionId, but milestoneSetId and milestoneId semantics (e.g. scoping or whether a set must be open) are left entirely to inference from parameter names.

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

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

Names a specific verb+resource ('Record that one saved acceptance criterion was met') and scopes the effect precisely. It does not explicitly name the sibling that handles the larger action (declare_milestone_complete), though the final sentence implicitly carves that out.

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 clearly ('The criterion must already be saved') and rules out the most likely misuse by saying it does not complete the milestone or release payment, which routes the agent to declare_milestone_complete / declare_next_payment_released for those outcomes. No sibling is named explicitly, 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 readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=false, so the write/safety profile is covered. The description adds genuinely new behavioral context beyond that: the post-approval refusal rule and the dependency on an accepted add_criterion suggestion. It does not explain why destructiveHint is true or what is overwritten on repeated saves.

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 the core purpose front-loaded, followed by the gating constraint and the non-completion clarification. No filler, no 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?

An output schema exists so return values need no explanation, and annotations cover the safety profile; the description supplies the non-obvious refusal rule an agent would otherwise trip over. The remaining gap is parameter guidance for a 0%-coverage schema, which is scored separately.

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 three required parameters (milestoneSetId, milestoneId, statement), so the description carries the full burden of explaining them. It says nothing about the distinction between milestoneSetId and milestoneId or the 500-character statement limit, adding no meaning beyond the bare parameter names.

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

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

States a specific verb+resource ('Save one acceptance criterion') and defines the resource's meaning ('what done means for that milestone'). It implicitly differentiates from save_deliverable/save_work_item by defining the artifact, but never explicitly contrasts them, so sibling differentiation is soft rather than sharp.

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 when-not condition ('after milestones are approved, a new criterion is refused until an accepted add_criterion suggestion') and a disambiguation ('This does not mark the milestone complete'), which steers agents away from declare_milestone_complete. It lacks an explicit positive trigger statement ('use when defining done criteria for a not-yet-approved milestone'), leaving part of the routing 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 only declare it as a non-idempotent write with destructiveHint=true; the description adds the approval-gate refusal rule and an anti-hallucination warning ('do not invent a deliverable that was not saved'), which an agent cannot get from the structured fields. It does not, however, explain why the tool is flagged destructive or what the write replaces.

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, no padding, with the core purpose front-loaded. The middle sentence is slightly dense but every clause carries useful 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?

An output schema exists, so return values need no explanation, and the approval-gate behavior is covered. The remaining gap is parameter meaning: with 0% schema coverage and no parameter prose, an agent must guess the role of the two UUID fields.

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

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

All four required parameters (milestoneSetId, milestoneId, title, detail) have 0% schema description coverage and the description explains none of them. 'Belongs to a milestone' only faintly hints at the milestoneId linkage and gives no identity/format guidance for the UUID pair or expected content for title/detail.

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

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

States a specific verb and resource: 'Save one deliverable that belongs to a milestone', which is distinct from the sibling resources save_work_item and save_acceptance_criterion. It does not explicitly differentiate itself from those siblings, 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?

Provides a concrete exclusion condition: after milestones are approved, an extra deliverable is refused until an accepted add_deliverable suggestion. That is real when-not guidance, though it never names the sibling tools an agent should prefer instead.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description adds a significant behavioral rule: after milestone approval, new work is refused until an accepted add_work_item suggestion. It also clarifies that unsaved work cannot be marked done, which is useful context. It does not explain the destructiveHint or what exactly gets destroyed or overwritten.

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

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

The description is three short, front-loaded sentences that each convey distinct information: purpose, approval constraint, and dependency on marking work done. There is little waste, though the final sentence could be seen as slightly redundant given the first.

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 a simple mutation with an output schema, so return values need not be described. However, the description does not make up for the complete lack of parameter documentation and leaves the destructiveHint unexplained, so it is only partially complete for an agent needing to call 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?

Schema description coverage is 0%, so the description must compensate for parameter documentation, but it only vaguely implies that a milestone is involved ('under a milestone'). It does not explain the roles of milestoneSetId, milestoneId, or title, nor how they relate to each other.

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 ('Save') and resource ('one piece of work under a milestone'), making the core action clear. It also implies a workflow relationship with 'so it can later be marked done,' but it does not explicitly name or contrast with sibling tools like save_deliverable or save_acceptance_criterion, so sibling differentiation is missing.

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 by linking it to later marking work done and noting that unsaved work cannot be marked done. However, it offers no explicit guidance on when to choose this over alternatives such as save_deliverable, and no conditions for use are spelled out beyond the implied 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 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?

Even though annotations declare destructiveHint=true and idempotentHint=false, the description adds real governance context beyond them: once approved, alternate wording is refused until an accepted revise_client_wording suggestion, and the assistant must not stray from this wording or the facts in read_milestone_set. That immutability-like constraint is exactly the behavioral detail annotations can't express.

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 purpose, and each sentence carries a distinct rule (what it records, the refusal-after-approval constraint, the fact-sourcing limit). Slightly dense but 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, and the safety profile is covered by annotations. The description supplies the important behavioral rules for a destructive write. The main remaining gap is the unexplained milestoneSetId.

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 gives no explicit guidance on either parameter. The wording parameter is loosely implied ('what the assistant may tell the client'), but milestoneSetId is entirely unexplained and the 1-2000 length bound is never surfaced. With two undocumented params, 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?

States a specific verb+resource: recording the client-facing wording about milestones, done, completion, and payment release. An agent knows exactly what content this tool governs. It doesn't explicitly contrast with sibling tools like define_milestone or declare_milestone_complete, 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?

The description implies you use this to record governed client-facing wording, and notes the post-approval refusal rule referencing revise_client_wording. But it never states when/when-not to use this vs the many sibling tools, and revise_client_wording is not even in the sibling list, leaving the escalation path ambiguous.

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