Planner (proof-of-done)

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

Annotations already mark destructiveHint=true, but the description adds crucial behavioral context: the action is irreversible, it deletes ALL data categories, and it enforces a mandatory two-step challenge/confirmation barrier. This goes well beyond the structured annotations and sets correct expectations for an agent.

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

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

Two dense, purposeful sentences: the first fronts the irreversible destructive scope, the second explains the two-step invocation protocol and the user-consent guardrail. No wasted words.

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

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

For a destructive, multi-step account deletion tool, the description covers the essential invocation sequence, irreversibility, data scope, and consent requirement. It does not detail what the challenge/riddle looks like or the exact response format, but the schema covers parameter meanings and no output schema is expected. Minor gap: it could state what happens after the second call, but overall sufficient.

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

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

The input schema already provides 100% description coverage for all five parameters, so the baseline is 3. The description adds context about the two-step invocation flow but does not add meaning beyond the schema for individual parameters.

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

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

The description states a specific verb and resource: irreversibly delete the user's account and all associated data (projects, goals, evidence, history). It clearly distinguishes this account-level destructive action from sibling goal-delete and project-delete tools.

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

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

The description gives explicit when-to-use and how-to-use guidance: invoke without arguments first to receive a warning and challenge, then invoke a second time with confirmations. It also warns not to call without an explicit user request, which is critical for a destructive account-level operation.

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 say readOnly=false and idempotent=false, so the description carries the transparency burden. It adds meaningful behavioral detail: parent requirement, linter validation on the text, and auto-classification of the type by an LLM. This goes beyond what annotations or the schema alone reveal.

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 short and well-organized: core action first, then the premise definition, then constraints. Each sentence contributes useful information without fluff or repetition.

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

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

The description covers the essential operational constraints: the parent requirement, linter rules, and auto-classification. It does not explain failure behavior if the linter rejects text or what the response contains, but those are secondary for tool selection and basic invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: it explains that text is the premise for why the goal contributes to the parent and that goalId refers to the child goal in a parent→child edge. It does not add much about signpost, but the schema already describes it as optional.

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

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

The description states a clear verb and resource: 'Add an assumption to a goal edge (parent→this goal).' It defines what an assumption is, so an agent can distinguish this from siblings like goal-add-criterion or goal-add-note. The parent/root-goal constraint further sharpens what this tool does.

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 clear context for use: adding an assumption to a goal edge, with the important exclusion that root goals have no edge and therefore cannot use this tool. It does not explicitly name alternative tools, but the sibling context plus the focused description makes the intended use reasonably clear.

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

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

Annotations only say readOnly=false and non-idempotent=false; description goes far beyond: it discloses rejection behavior (error=probe_required), the implicit assignment of probeClass when probeSpec is present, the linter behavior in Grove mode, the frozen-edits rule, and the special recheck flow for visual advisories. This is exactly the kind of behavioral context the annotations don't cover.

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 dense and long, but every sentence contributes necessary operational knowledge. It front-loads the core contract (append + observable check) before diving into modes and constraints. Slightly heavy for a first scan, but the density is purposeful.

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?

Covers the full calling context: return value (criterion id, class, probeSpec, quality findings), mode-dependent behavior (Grove vs non-Grove), linter behavior, required probeSpec for post-deploy, and the visual-evidence adoption path. An agent can select and invoke this tool correctly without further external context.

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

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

Though the schema describes each parameter well, the description adds semantic meaning beyond field 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?

Opens with a specific imperative verb and resource: 'Append an acceptance criterion to a goal.' It then defines what a criterion is (an observable check over an artifact) with a concrete example, which disambiguates the tool from generic goal-update or goal-create operations.

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

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

Explicitly distinguishes pre-merge vs post-deploy classes, states when probeSpec is required, and explains when visualEvidenceSuggested should be set (only when adopting a suggestion from goal-create/goal-get/ready_for_work). Gives clear constraints per mode (Grove: AC only editable in backlog) and notes the visual advisory flow — no ambiguity about when to use this tool.

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

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

Description warns that plain evidence never counts toward AC coverage and does not close goals, a non-obvious side-effect that annotations cannot convey. It also clarifies the note is a complement to an attached file, giving the agent a mental model of the tool's limited scope. Since annotations only provide readOnlyHint/idempotentHint, the description carries the burden and meets 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?

The key information is front-loaded: subordinate path, does not close AC, text-only. Repetition of the goal-attach-evidence alternative across several sentences is a bit verbose, but each sentence adds a distinct exclusion (bytes, filesystem paths, AC coverage) that reduces mis-invocation risk.

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

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

For a simple 3-parameter tool with no output schema, the description covers what the tool does, what it intentionally does not do, and which sibling covers every excluded case. The only omission is return behavior, but that is not essential for selecting and invoking this tool correctly.

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

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

Input schema already fully documents all three parameters (100% coverage), so baseline is 3. Description restates the text payload constraint and adds exclusions (not for bytes/filesystem paths) that flesh out allowable values, but it introduces no new parameter-specific detail for criterionId or createdBy.

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: adds text-only evidence/note to an acceptance criterion. Explicitly distinguishes itself from sibling goal-attach-evidence by framing itself as supplementary/subordinate and clarifying it does not close an AC. Concrete examples (URLs to CI run, commit, issue, manual scenario) make the purpose unmistakable.

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 directs the agent to goal-attach-evidence for any criterion coverage or any byte/file/path payload, and states this tool is only for text-only supplementary context. Gives clear when-not conditions (not for bytes, not for filesystem paths) and the alternative to use. This is the strongest possible usage guidance.

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

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

Annotations only say the operation is not read-only and not idempotent. The description adds meaningful behavioral detail: notes hang off the goal rather than an acceptance criterion, they are not counted as evidence, they are visible in the goal detail panel, and they are returned by goal-get under notes[]. This goes well beyond what annotations provide.

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

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

The description is well-structured and front-loaded with the core purpose. Each sentence earns its place: one for what the tool does, one for the critical evidence distinction and alternative tool, and one for visibility and return behavior. No filler or redundant restatement.

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

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

For a simple two-parameter mutation tool with no output schema, the description is complete. It covers purpose, content guidance, non-evidence semantics, the sibling alternative, persistence behavior, and where results appear. An agent has enough information to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents goalId as a UUID and text as markdown. The description reinforces that the text is free-form markdown and describes the content intent, but it does not add meaning beyond the schema for either parameter. Baseline 3 is appropriate.

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

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

The description states a specific action and resource: 'Add a free-form note (markdown supported) to a goal'. It clearly distinguishes notes from evidence by naming the alternative goal-attach-evidence and explaining that notes are not acceptance-criterion proof. The purpose is unambiguous and easily differentiated from the many sibling goal-* tools.

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

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

The description gives explicit usage guidance: use notes for decisions, dead ends, and session context; do NOT use them as evidence because they never count toward AC coverage or goal closing. It names the exact alternative tool, goal-attach-evidence, and explains the selection condition.

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

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

The description discloses the full judgment state machine: supports→supported, first challenge→challenged, repeat challenge→invalidated, terminal invalidated, and fail-open behavior on judge infra failures. This goes well beyond the bare annotations (readOnly=false, idempotent=false) and tells the agent about destructive/irreversible terminal state changes and error semantics.

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 compact sentences, each carrying essential information: action, state transitions, and failure behavior. No filler words or redundant restatements of the tool name.

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

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

For a two-parameter tool with complex side effects, the description explains the complete state-transition behavior and failure mode. It does not state the response/return shape, but with no output schema and clear state-change semantics this is a minor gap rather than a blocking omission.

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?

Input schema covers 100% of parameters, so the baseline is 3. The description references 'text evidence' and 'assumption' but adds no parameter-specific meaning beyond the schema's UUID and text descriptions. No compensation is needed because schema coverage is complete.

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 action ('attach text evidence to an assumption and judge it') and a concrete resource, and the judge/status-transition behavior distinguishes it from sibling tools like goal-add-evidence-text and goal-attach-evidence. The state machine is described precisely, so an agent knows exactly what this tool does.

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

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

The description implies the primary use case (adding text evidence to an assumption with automatic evaluation) but does not explicitly state when to prefer it over sibling tools such as goal-add-evidence-text or goal-attach-evidence, nor does it give exclusions. There is no 'when not to use' guidance; the usage context must be inferred.

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

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

With only readOnlyHint=false and idempotentHint=false (no safety coverage), the description carries full burden and exceeds it: it discloses the known agent-side failure mode with measured data ('a 4 KB PNG arrived at the server as 1874 decoded bytes (file_hash_mismatch)'), the validation rules (MIME whitelist, 25 MiB cap, per-project quota), the fast-fail behavior on hash mismatch, and the return shape (evidence record + file URL + serverSha256). It also clarifies the kind=session_history semantic (does NOT cover an AC, not sent to judge). This is substantial disclosure far beyond the annotations.

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

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

Well front-loaded (purpose → routing warning → recipes) and hierarchical, but overly verbose: the planner-attach.sh copy-paste recipe, curl invocation details, and multipart POST fallback occupy several paragraphs. The core routing decision could be compressed, and some transport/recipe detail could be trimmed without losing the decision-critical guidance. Every section earns some place, but the length is bloated.

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

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

For a high-complexity tool (8 params, transport selection, validation rules, documented failure modes, no output schema), the description is remarkably complete: it states return values ('Returns evidence record + file URL + serverSha256', 'Output on stdout is the same JSON shape this MCP tool returns'), covers the session_history special case, gives security context (no token needed on the upload path, signed ticket is single-use), and explains when each transport is appropriate. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond schema on the riskiest params: contentBase64 is flagged as unreliable ('long string arguments get truncated or whitespace-corrupted on the agent side BEFORE the JSON-RPC request is sent'), contentSha256 is explained as the integrity defense that makes the server 'fast-fail with error=file_hash_mismatch', and criterionId is traced to its source ('the AC id you got from goal-get / goal-list'). This enriches the schema without duplicating it.

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

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

Opens with a precise statement of verb, resource, and scope: 'PRIMARY path to close a Grove goal: this is the ONLY tool that covers an acceptance criterion. Attach binary evidence... to an AC — call it once per criterion to satisfy the close gate.' It differentiates explicitly from goal-add-evidence-text (does NOT cover an AC) and implies distinction from goal-attach-assumption-evidence and goal-attach-file. An agent can tell exactly what this tool does and what it is not.

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 explicit, condition-based routing: 'File ≤ ~1 KB raw → this MCP tool is fine' vs 'BEST for ANY file > ~1 KB raw... call the sibling MCP tool goal-request-upload'. It names goal-request-upload as the alternative, states when NOT to use this tool (non-trivial files due to agent-side base64 truncation), and gives a multipart fallback. Nothing is left to inference.

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

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

With only readOnlyHint=false and idempotentHint=false annotations, the description carries the behavioral burden and does so well: it discloses the return shape, the markdown rendering behavior, the ~1KB reliability limit for contentBase64, and the truncation risk for long string arguments.

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 focused paragraphs with no filler. The core purpose and not-evidence caveat are front-loaded, followed by the return format, integration step, size limitation, and alternative path — every sentence earns its place.

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

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

There is no output schema, so the description correctly explains the return object and how to use the markdown. It also covers the size threshold, the fallback upload flow, and the fact that the result shape is the same, making the tool self-sufficient for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value on top by warning that contentBase64 is only reliable for payloads ≤ ~1KB and that larger files must go through goal-request-upload, which is critical for correctly supplying the contentBase64 parameter.

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

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

The description opens with a specific verb and resource: 'Attach a small file ... to a GOAL as a description attachment.' It explicitly differentiates from evidence attachments by stating the file is 'NOT evidence,' 'not bound to any acceptance criterion,' and 'never counts toward closing the goal,' which makes it distinguishable from sibling tools like goal-attach-evidence.

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 clear when-to-use/when-not-to-use guidance: use this tool for small description attachments, and 'For anything bigger call goal-request-upload.' It also tells the agent how to follow through by pasting the returned markdown into 'goal-update description.'

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 say readOnlyHint=false and idempotentHint=false. The description goes well beyond them by disclosing that blockers are additive, that calling this sets status to blocked, that resolver creation/linking is mutually exclusive, and that removing the last active blocker restores the previous status. No contradictions with annotations.

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

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

Four short sentences pack in the core action, additive behavior, status effect, resolver options, mutual exclusivity, and restoration rule. Nothing is redundant and the most important facts come 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?

For a write operation with no output schema and minimal annotations, the description is unusually thorough: it covers side effects, optional resolver handling, and lifecycle behavior. It could still be slightly more complete by clarifying that resolverParentId/resolverDescription only apply to the inline-creation path, but this is inferable from 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 100%, so the schema already documents all six parameters. The description adds a little context by naming resolverTitle and linkedGoalId and restating their mutual exclusivity, but it does not need to compensate for gaps; baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Add a blocker to a goal', and immediately distinguishes this from many sibling tools by noting blockers are additive and set the status to blocked. It also names the related goal-remove-blocker tool, so an agent can tell this is the blocking operation, not a note/assumption/criterion operation.

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

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

The description clearly conveys when to use it: any time a blocker should be added to a goal, including the status effect and optional resolver behavior. It doesn't explicitly list alternative tools to prefer for related-but-different operations, but the blocker-specific semantics and reference to goal-remove-blocker give enough context to choose correctly.

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

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

Annotations only state readOnly=false and idempotent=false. The description adds meaningful behavioral detail: return shape (id, webUrl, mode, nextStep), enforcement differences between grove and standard modes, potential probe_required errors, and the advisory visualAcSuggestion response behavior.

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 dense but organized into a compact main narrative plus structured parameter details. Some phrasing is mixed-language and slightly redundant, but the key behavior, return value, and constraints are presented without excessive filler.

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

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

The description covers return value, mode behavior, acceptance criteria requirements, project membership, and an important error case. It does not enumerate all possible errors or side effects, but for a create operation with no output schema, the context provided is sufficient.

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

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

Schema coverage is 100% with descriptions for all 12 parameters, including defaults, constraints, and nested acceptance criteria structure. A few descriptions are terse or jargon-heavy (e.g., 'I_start', 'I₃', 'Теги'), but overall the semantics are sufficiently clear for invocation.

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

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

The description states a specific verb ('Create') and resource ('goal/task/milestone/habit in the planning tree'), including constraints like project membership and mode behavior. It clearly distinguishes the creation action from related goal operations.

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

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

The description gives practical usage context, such as when ready_for_work must be declared via goal-update and when post-deploy criteria require probes. It does not explicitly enumerate sibling alternatives, but the creation scope and the goal-update status caveat provide reasonable guidance.

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

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

Annotations already mark the operation as destructive and idempotent, and the description adds meaningful behavioral context beyond that: the cascade behavior to descendants, irreversibility, and the exact return value (deleted title and children_deleted count). This gives an agent a full picture of the action's effects without contradicting the annotations.

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

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

Three sentences with no filler: the destructive scope is front-loaded, alternatives and usage policy are stated next, and the return value appears last. Every sentence 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?

For a one-parameter delete tool, the description is complete: it covers scope, effects, when to use alternatives, and the return value despite the absence of an output schema. No critical detail for correct invocation is missing.

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

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

Schema coverage is 100% and the only parameter, goalId, is already described as a UUID in the schema. The description does not add new parameter-specific meaning, but it implies the goal's identity is the target of deletion. This meets the baseline for high schema coverage but does not exceed it.

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

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

The description opens with a specific verb and resource: 'IRREVERSIBLY delete a goal and all its descendants,' listing exactly what is removed (children, evidence, blockers). It also distinguishes itself from sibling tools by naming goal-update and goal-block as alternatives, so an agent can immediately tell this apart from related operations.

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

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

The description explicitly states when to use this tool versus alternatives: prefer goal-update status=cancelled for preserving history, use goal-block to mark obstacles, and use delete only for erroneous or duplicate entries. This is unusually clear routing guidance.

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

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

Beyond the annotations, the description discloses meaningful behavioral traits: the dismissal is recorded in goal history, surfaced in goal-get, and remains distinguishable from 'no hole was found'. It also states the long-term consequence that the hole remains open, which is critical for an agent deciding whether to invoke this mutation.

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

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

The description is three focused sentences, each earning its place: the first defines the action and condition, the second explains the requirement and audit trail, and the third provides the safer alternative. It is front-loaded with the core purpose and contains no redundant 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?

For a simple two-parameter mutation tool, the description is complete: it covers purpose, when to use, requirements, consequences, and the preferred alternative. The annotations already indicate this is not read-only and is idempotent, and the description adds the remaining behavioral context an agent needs 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?

The schema already provides 100% parameter coverage, including goalId and a detailed Russian description of reason requiring at least 80 characters. The tool description mostly restates the reason requirement rather than adding new semantic detail, though it usefully frames the reason as explaining 'why the counterexample does not apply'.

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

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

The description states a specific action ('Dismiss the red-team finding that blocks a goal from starting') and the condition for using it ('when you disagree with the verdict'). It clearly distinguishes itself from nearby alternatives like goal-add-criterion by explaining that dismissing is not the same as fixing the underlying hole.

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

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

The description explicitly tells the agent when to use the tool ('when you disagree with the verdict'), what is required (a reason of at least 80 characters), and which alternative to prefer ('Prefer fixing the acceptance criteria via goal-add-criterion'). It also warns that dismissing leaves the hole open, giving a clear reason to avoid this tool unless necessary.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds useful detail about the returned payload: children, acceptance criteria with evidence coverage, blockers, history log, and project. This goes beyond the annotation without contradicting 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?

Two sentences with no filler. The action and main scope are front-loaded, the field enumeration is compact, and the usage context is stated efficiently.

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

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

With one simple parameter, readOnly annotation, and no output schema, the description carries the return-value burden by enumerating the full detail set. Nothing essential is missing for an agent to call this tool correctly.

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

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

Schema coverage is 100% and the single goalId parameter is self-explanatory. The description reinforces that the parameter identifies 'a single goal' but adds no deeper semantic detail; baseline 3 is appropriate given the complete schema coverage.

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

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

The description opens with a specific verb and resource: 'Fetch full details of a single goal' and enumerates the exact fields returned. It also positions the tool as 'the primary drill-down tool after goal-list or goal-tree,' which distinguishes it from sibling list/overview tools.

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

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

It clearly states when to use the tool: after goal-list or goal-tree, as the drill-down step. It does not explicitly mention when not to use it or name alternatives like goal-summary, so it stops short of full exclusion guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavioral details: no offset pagination, default limit of 50, deterministic sorting by priority then createdAt, and the fact that parentId filters to direct children only. These details help an agent predict what the tool returns and how it behaves before calling 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?

The description is compact and well-structured: it states the operation, lists filters, then provides result behavior and output fields. Each sentence adds useful information without redundancy.

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

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

For a read-only filtered list tool with no output schema, the description covers the essential contract: available filters, result limit behavior, sorting order, and the exact fields returned. No critical information for invoking the tool correctly is missing.

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

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

Input schema coverage is 100%, so the schema already documents each parameter. The description adds value by clarifying 'direct children only' for parentId, the default limit, and the absence of offset pagination, which are not explicit in the schema.

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

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

The description uses a specific verb 'List' with a clear resource 'goals' and enumerates the available filters. It differentiates itself from siblings like goal-get or goal-tree by framing this as a filtered listing operation with a bounded result set.

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

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

The description clearly conveys that this tool is for listing goals with optional filters and result limits, but it does not explicitly state when to prefer it over related tools like goal-get or goal-tree. The usage context is implied rather than directly contrasted with alternatives.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses two important side effects: the project change cascades to all descendants, and cycles are prevented. This gives an agent critical knowledge about blast radius and safety that the annotations alone do not provide.

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

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

Three compact sentences express the purpose, parameter behavior, and side effects with no filler. The purpose is front-loaded, and every sentence adds operational value.

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

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

For a mutation tool with no output schema, the description covers all essential aspects: required and optional parameter semantics, conditional behavior (root vs reparent), cross-project moves, descendant cascade, and cycle protection. No critical operational detail is missing.

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

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

The schema already documents all three parameters, so the baseline is 3. The description adds meaningful interaction semantics: newParentId=UUID reparents and inherits the parent's project, newParentId=null roots the goal, and projectId overrides the target project only in the root case. This enriches the schema without redundancy.

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

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

The description opens with a specific verb and resource ('Move a goal to a different parent or project'), which clearly states the tool's operation. It also distinguishes this from sibling tools like goal-reorder or goal-update by focusing on changing parent/project rather than reordering or editing fields.

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

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

The description gives a clear use case and detailed parameter-based instructions, but it never explicitly says when to prefer this tool over siblings such as goal-reorder or goal-update. No alternatives or exclusions are mentioned, so the usage guidance is only implied.

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

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

Annotations declare readOnlyHint and idempotentHint, but the description adds substantial behavioral detail: text secrets are redacted, binary evidence is unmodified, images return native MCP images, and binary delivery has two modes with distinct trade-offs. This goes well beyond the annotations and helps the agent anticipate outcomes.

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

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

The description is a single dense paragraph that front-loads the core action and then systematically covers text vs binary behavior, delivery options, and parameter requirements. Every sentence adds operational value—no fluff or redundancy. The structure is logical and easy to parse.

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

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

Despite the complexity of the tool (binary vs text, pagination, redaction, delivery modes, and output types), the description covers everything an agent needs: how to obtain evidenceId, how text and images are returned, how to handle binaries via link or base64, and the trade-offs of each. With no output schema, the description carries the full burden and meets it.

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

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

Although schema coverage is 100%, the description adds crucial parameter semantics not fully captured in the schema: offset/limit are zero-based line pagination for text, byteOffset/byteLimit require binaryDelivery=base64, and binaryDelivery=link returns a resource_link to the authenticated original download. This clarifies how parameters interact and their practical implications.

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

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

The description clearly states the tool's purpose: 'Read attached evidence through MCP without changing its format.' It specifies the resource (evidence) and the action (read), and it explicitly tells the agent to 'Pass evidenceId from goal-get,' which ties it to the sibling goal-get tool. This differentiates it from other goal-* tools that create, attach, or modify evidence.

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 precise usage instructions: it explains when to use link vs base64, when byteOffset/byteLimit are required, and notes that base64 expands data and can consume context window, so 'use it only when needed.' It also instructs the agent on how to obtain evidenceId from goal-get. This is explicit when-to-use and when-not-to-use guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses useful behavior: single-project scoping, a createdAt freshness window, enriched return fields (title/description-preview/parent/counts), and the pickup-status semantics. But the disclosure is undermined by the same backlog contradiction — the default filter would return goals the description declares unusable — so the behavioral picture is not fully reliable.

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 sentences, front-loaded with the purpose phrase 'Pull-инбокс для «подхватить и довести»', with scoping and return-format details packed densely but readably. The trailing parameter enumeration is redundant given 100% schema coverage, which is the only notable waste.

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

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

For a tool with no output schema, the description covers the essential return contract (enriched records with title/description-preview/parent/counts) and the filter contract (project, withinDays, statuses, limit). Gaps remain: no sort-order semantics despite 'recent' in the tool name, and the unresolved default-vs-guidance conflict over backlog statuses.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description's restatement of project/withinDays/statuses/limit adds little beyond the schema. It does add interpretive value by explaining the executor-queue meaning of ready_for_work and checking_ac_errored, but the 'backlog нельзя брать' note conflicts with the schema-documented default, weakening that added semantics.

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

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

The description names a specific resource and action: a 'pull-inbox' for pick-up-and-finish workflows, scoped to one project, a recency window, and status-based filtering. It explicitly differentiates itself from sibling goal-get by noting it returns enriched records 'чтобы выбрать без goal-get' (to choose without goal-get), and its focus is distinct from goal-list, goal-tree, and goal-todo.

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 frames when to use it — a pickup session for the executor's queue (ready_for_work, checking_ac_errored) — and contrasts it with goal-get for selection. However, the status guidance is internally contradictory: it states 'backlog-цели брать нельзя' (backlog goals cannot be taken) while the statuses parameter defaults to ["backlog"], so an agent following the default would request items the description says to avoid.

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?

With only readOnlyHint=false and idempotentHint=false as annotations, the description carries the behavioral burden and does so well. It discloses validation requirements, a server-side derivation ('Planner derives the repeat verdict server-side'), and a side effect (affects the numeric implementation rework rate), with no contradiction to the annotations.

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

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

Four dense sentences are front-loaded with the primary purpose and followed by constraints and scope. There is no filler or redundant explanation; each clause earns its place.

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

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

For a 12-parameter mutation tool with no output schema, the description plus fully covered input schema gives an agent enough to operate in normal and rework cases. Minor gaps remain: 'current tracked contract' is not defined, the relationship to goal-register-iteration-finding is implicit, and return/error behavior is not described.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining rework conditions, the requirement for a separate judged evidence row, and the server-side derivation behavior. These details add operational meaning that the property descriptions alone do not fully convey.

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

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

The description states a specific action ('Record one completed LeanSolver iteration') against a clear resource ('the current tracked contract') and then gives domain-specific constraints that separate it from sibling recording/finding tools. The final sentence about only certificates admitted here affecting the rework rate further pins down the tool's unique role.

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 practical use conditions: artifact refs must already exist and be goal-owned, rework iterations require registered finding IDs, and repeatCheckEvidenceId is mandatory. It does not explicitly name sibling alternatives or say 'use this tool when X, not when Y,' but the preconditions are clear enough to route an agent.

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

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

The description reveals that findings are immutable, the operation returns a server-generated ID for later use in addressesFindingId, and it rejects stale contract tracking. These behaviors go well beyond the annotations, which only say readOnlyHint=false and idempotentHint=false.

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 tight sentences front-load the core action and then cover constraints, return value, and failure behavior. Every sentence earns its place with 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?

For a mutation tool with no output schema, the description covers the essential return value, key constraint on subjectRefs, and the stale-tracking rejection. It leaves some domain terms intentionally implicit, such as what exactly qualifies as 'stale', but the core invocation guidance is complete enough for correct use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful constraint detail beyond the schema by specifying that subjectRefs must be goal-scoped refs of kind goal, criterion, or assumption, and by explaining how the returned ID relates to a later parameter, addressing semantics that the schema alone does not convey.

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 ('Register'), resource ('immutable LeanSolver finding'), and target ('currently tracked goal contract'). The term 'finding' distinguishes this from the sibling goal-record-iteration-certificate, and the mention of tracking context separates it from general goal mutation tools.

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

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

Clear context is given: this is for findings against the currently tracked goal contract, and stale contract tracking is explicitly rejected. It does not explicitly name alternatives or state when-not-to-use relative to sibling tools, but the tracking prerequisite and staleness rejection provide practical usage boundaries.

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 communicate that this is a mutating, idempotent operation, so the description does not need to restate those traits. The phrase 'from a goal edge' adds some context about the target, but it does not clarify side effects, such as whether the assumption is also deleted or only unlinked.

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

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

The description is a single concise sentence that is front-loaded and contains no filler. Every word contributes to stating the tool's core action and target.

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

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

For a simple one-parameter, idempotent mutation with full schema coverage, the description is nearly complete. The only minor gap is ambiguity about whether removal affects the assumption entity itself or only the edge, but this does not impede the agent from invoking the tool correctly.

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

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

Schema description coverage is 100%, and the only parameter is documented as 'UUID допущения,' which adequately identifies the assumption UUID. The description adds no additional parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource, 'Remove an assumption from a goal edge,' which clearly identifies the operation. It differentiates from siblings like goal-add-assumption, goal-update-assumption, and goal-remove-criterion by naming both the resource and the location of the removal.

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

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

No guidance is given about when to use this tool versus alternatives. It does not mention conditions, prerequisites, or situations where a different sibling such as goal-update-assumption or goal-remove-criterion would be more appropriate.

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

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

Annotations only indicate readOnlyHint false and idempotentHint true. The description adds meaningful behavioral detail beyond that: automatic goal status restoration when the last blocker is removed, and preservation of the linked resolver goal. This gives the agent important side-effect knowledge without contradicting the annotations.

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

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

The description is compact: a primary action sentence followed by two concise behavioral caveats. Every sentence adds distinct value, and the main operation is front-loaded for quick parsing.

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

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

For a two-parameter mutation tool with clear annotations, the description covers the central action and the relevant edge cases. The parameter details are already fully documented in the schema, so nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, and both required parameters are already described as UUIDs. The description restates that the blocker is identified by UUID, but adds no additional format, constraint, or relationship semantics beyond what the input schema already provides.

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

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

The description opens with a specific verb and resource: 'Remove a blocker from a goal by blocker UUID.' It clearly differentiates from sibling removal tools by naming the blocker as the removed entity, and the final sentence adds a useful boundary by clarifying that the linked resolver goal is not deleted.

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

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

The context for use is clear: this is the tool for removing a blocker from a goal. While it does not explicitly name alternatives like goal-remove-assumption or goal-remove-criterion, the resource-specific wording and side-effect caveat make the intended usage unambiguous enough for selection among siblings.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses a critical side effect: removal 'Cascades to all evidence on the criterion.' It also states the return behavior ('confirmation with removed criterion details'), adding meaningful behavioral context 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?

Four short sentences, each delivering distinct information: the action, mode constraints, cascade side effect, and return confirmation. No filler or redundant restatement of the tool name.

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

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

For a single-parameter tool with no output schema, the description covers when the operation is allowed, what side effects occur, and what the response contains. This is sufficient for an agent to invoke it correctly without ambiguity.

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

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

The schema already documents criterionId as 'UUID acceptance criterion' with 100% coverage. The description does not add parameter-level detail beyond that, so the baseline of 3 is appropriate; the schema carries the parameter semantics.

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

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

The description opens with a specific verb and resource: 'Remove an acceptance criterion from a goal.' It clearly differentiates from siblings like goal-remove-assumption, goal-remove-evidence, and goal-remove-note by naming the exact object being removed.

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

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

The description provides clear context for when removal is permitted: Grove mode only while in backlog, standard mode until done. It does not explicitly name alternative tools or exclusions, but the mode-based timing constraints give an agent actionable guidance on when this tool applies.

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

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

Beyond the annotations indicating a mutating operation, the description discloses important side effects: it removes both the database record and any attached file. It also reveals the freeze condition after goal close, which is critical behavioral context not available from the schema or annotations.

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

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

The description is three sentences with no filler. The primary action is front-loaded, followed by the most important precondition and the side-effect of file removal. Every sentence earns its place.

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

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

For a single-parameter delete tool, the description is complete: it states the action, the target identifier, the key precondition, and the full scope of what gets removed. The annotations already cover mutability and idempotency, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents the evidenceId parameter as a UUID. The description reinforces that deletion is by UUID but does not add new parameter-level details beyond what the schema already provides.

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

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

The description starts with a specific verb and resource: 'Delete an evidence record by UUID.' This clearly identifies the operation and the object it acts on, and distinguishes it from sibling tools that remove notes, assumptions, or criteria.

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

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

The description gives clear context for when deletion is allowed and explicitly states a key exclusion: it is forbidden when the owning goal is already done. It does not name alternative tools, but the operation is specific enough that the main usage intent is unambiguous.

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

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

Annotations already declare destructive and idempotent behavior. The description adds useful behavioral context by scoping the deletion precisely: it removes only the note and never touches acceptance criteria, evidence, or blockers. This adds value beyond the annotations.

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

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

The description is two concise sentences with no filler. The core action is front-loaded, and the important clarification about scope and note ID provenance is immediately useful.

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

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

For a simple two-parameter mutation tool, this description is complete: it states the action, the parameter source, and what it intentionally does not affect. Annotations cover safety and idempotency, so no critical behavioral gap remains.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter context by explaining that noteId comes from goal-get's notes[].id field, which helps an agent obtain the correct value rather than guessing.

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

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

The description uses a specific verb and resource: 'Remove a note from a goal by note UUID.' It clearly differentiates from sibling removal tools by stating it 'never touches acceptance criteria, evidence or blockers.'

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

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

The description provides clear usage context, including where note IDs come from ('goal-get (notes[].id)') and an explicit statement of what this tool does not affect. It does not name specific alternative sibling tools, so it stops short of fully explicit when-to-use-this-versus-that guidance.

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

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

Annotations already indicate the operation is non-read-only and idempotent. The description adds meaningful behavioral detail by specifying that each goal is assigned position equal to its array index and that all goals must be siblings with the same priority, which clarifies the exact effect of the call.

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

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

Two sentences with no filler. The first sentence states the operation and its scope, the second explains the array-index mechanics and the constraint. Every sentence earns its place.

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

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

For a single-parameter tool with no output schema and annotations covering read-only and idempotence, the description captures what an agent needs to invoke it correctly. A brief pointer to goal-move for reordering across different parents or priorities would make it fully complete.

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

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

Schema coverage is 100% because the ids parameter is documented, so the baseline is 3. The description adds value by defining the mapping rule (position equals array index) and restating the same-parent/same-priority constraint in clear English, going slightly beyond the schema text.

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

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

The description opens with a specific verb and resource: 'Set display order of sibling goals within the same parent and priority band.' This clearly distinguishes the tool from goal-move and other goal mutation siblings by specifying the scope and the action.

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

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

The description clearly states the conditions for use: all goals must share the same parent and priority, and the array order defines the display order. It does not explicitly name an alternative tool for moving goals across parents or priorities, so it stops short of full when-not-to-use guidance.

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

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

Annotations only say the tool is not read-only and not idempotent; the description adds meaningful behavioral context: an LLM judge screens the reason, quotedFragment is checked against stored text, and a successful request creates an escalation for the goal owner. It also discloses the possible resolution outcomes, making the post-call behavior clear.

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

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

The description is dense but well-structured: a clear purpose sentence, followed by ground-specific rules, validation details, and outcome information. Every clause earns its place, and the length is justified by the branching logic of two ground types plus prerequisites.

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

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

The description covers prerequisites (Grove mode, in_progress goal), evidence requirements, validation rules, rejection of weak reasons, and post-escalation behaviors. It does not specify the exact return value on rejection, but this is minor given how thoroughly it guides correct use; the agent has enough to invoke the tool correctly.

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

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

Although schema coverage is 100%, the description adds significant semantics beyond the schema: it explains how grounds changes requirements, what quotedFragment must contain and that it is verified, and what the reason field must articulate for each grounds value. This materially helps an agent construct valid arguments.

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 opening sentence states a specific verb and resource: 'Request a change to an acceptance criterion.' The description then clarifies this is an escalation request rather than a direct edit by noting it 'creates an escalation for the goal owner to resolve,' which separates it from siblings like goal-update-criterion and goal-remove-criterion.

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 detailed conditions for when each grounds value is appropriate: unreachable requires ≥3 failed evidence attempts, while wrong_criterion requires no failed attempts but mandates a quotedFragment. It also explicitly excludes difficulty alone as a valid reason and scopes usage to Grove mode with in_progress goals. It does not explicitly name sibling alternatives, though it implies them through the escalation 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?

The description reveals critical behavioral details beyond the readOnly/idempotent annotations: one-time uploadUrl, expiry, raw PUT streaming without base64/token, optional SHA-256 for corruption detection, non-2xx rejection semantics, and that no evidence is created on failure. It also explains the goal-attachment branch and its markdown return value.

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 long but information-dense, with the primary use case front-loaded, followed by concrete curl examples, failure semantics, and alternative-tool routing. Each paragraph earns its place and the structure is easy to scan.

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

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

Given the tool's real complexity and no output schema, the description is remarkably complete: it covers the request response, the PUT protocol, the optional hash, the response shape, failure handling, and the goal-attachment variant. An agent has enough to call it correctly without additional inference.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces the goalId/criterionId mutual exclusivity and kind's accepted value, but it mostly repeats schema information rather than adding substantially new parameter-level meaning.

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

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

The description states a specific verb and resource: 'PREFERRED path to attach a LARGE binary evidence file ... to an acceptance criterion.' It clearly delimits the tool's job from goal-attach-evidence and goal-add-evidence-text, so an agent can tell them apart immediately.

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 guidance is explicit: 'Use this instead of goal-attach-evidence for any non-trivial file' and 'Use goal-add-evidence-text only for byte-less context' with the note that it does not cover an AC. It also explains when to pass goalId instead of criterionId, giving clear routing rules.

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

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

The description discloses a critical behavioral trait beyond the annotations: 'All prior evidence on the AC is deleted for edit/split/drop so the agent must submit fresh proof.' This is exactly the kind of destructive side-effect an agent needs to know. The annotations only indicate non-read-only and non-idempotent, so this disclosure carries the safety burden and does it well.

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 resource, with zero filler. Each sentence earns its place: the first covers purpose and options, the second covers the destructive consequence.

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

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

For a tool with no output schema, the description covers the main decision workflow, parameter dependencies, and the key side-effect of deleted evidence. It does not explain what the response looks like or the meaning of overrideResolvedBy, but the core invocation logic is complete enough for an agent to act 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 high at 83%, and the description adds meaningful semantics by explaining each resolution mode and its parameter implications: edit requires newText, drop optionally uses linkedGoalId as an audit reference, split moves the AC to a child goal. However, the overrideResolvedBy parameter is not mentioned or explained, leaving a small gap.

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

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

The description uses a specific verb ('Resolve') with a clear resource ('pending AC escalation') and enumerates the four resolution modes: edit, split, drop, and reject. This makes the tool's purpose unambiguous and distinguishes it from related goal tools like goal-request-ac-change.

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

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

The description clearly states when to use this tool (to resolve pending escalations) and gives concrete context for each resolution mode, including that reject means the agent must find another way. It does not explicitly name sibling alternatives or say when not to use it, but the context is strong enough for an agent to route correctly.

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

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

Annotations already provide idempotentHint=true and readOnlyHint=false, but the description adds the server-side fingerprint computation, the condition for starting a new version, and the retention of old certificates as superseded history. This clarifies consequences beyond the structured hints, though it does not address errors or prerequisites in depth.

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 focused sentences with the core action first. The follow-up sentence earns its place by explaining idempotence and versioning, and there is no filler or redundant 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?

The definition covers the main operational context: when a new version begins and what happens to prior certificates, with the only gap being the lack of return-value or error information since no output schema exists. For a one-parameter, state-changing tool this is still largely complete.

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

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

With 0% schema description coverage, the description carries the burden for parameter meaning, but it never mentions goalId, its format, or how it relates to the 'goal contract currently stored by Planner'. The name and schema imply it is the goal identifier, but the description adds no semantic value.

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

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

The description opens with a specific verb-resource pair: 'Explicitly start LeanSolver iteration tracking' for the goal contract held by Planner. This clearly separates it from siblings like goal-record-iteration-certificate and goal-register-iteration-finding, which record artifacts rather than start the tracking lifecycle.

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 establishes when to call: at the start of tracking for the currently stored goal contract, and indicates that re-calling after a contract change starts a new version while re-calling without a change is safe. It does not explicitly name when-not-to-use or alternatives, so it stops just short of a top score.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds meaningful behavioral context: it is LLM-generated, non-persisting, and returns 2-4 assumptions with signposts and type classification. This goes beyond the structured annotations without contradicting them.

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

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

Two sentences, both high-value: the first defines exactly what the tool returns and for what relationship; the second tells the agent/author what to do next. No filler or redundancy.

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

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

For a single-parameter, read-only, idempotent suggestion tool, the description covers what is produced, how many items, their attributes, and the follow-up action. The absence of an output schema is compensated by the explicit return description.

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

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

Schema description coverage is 100% — the schema already documents goalId as the child goal's UUID. The description reinforces this by mentioning the parent→child edge, but it does not add substantial new parameter semantics beyond what the schema provides.

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

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

The description states a specific verb ('generates'), resource ('suggested assumptions for a goal edge'), and scope ('parent→child'). It also differentiates itself from the sibling goal-add-assumption by noting that acceptance happens through that tool.

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

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

The description provides clear post-use guidance: the author should review, edit, and accept relevant assumptions via goal-add-assumption. It implies when to use this tool (when suggestions are wanted before committing), though it does not explicitly state exclusion conditions or when not to use it.

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

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

Annotations already mark it readOnlyHint=true, and the description adds the behavioral detail of what aggregation and scoping occur. It clearly enumerates the computed statistics, which is useful context beyond the annotation. No contradictions found.

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

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

Two sentences, front-loaded with the operation and metrics, with no filler or repetition of schema details. Every clause earns its place.

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

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

For a simple read-only aggregation tool with one optional parameter and no output schema, the description fully specifies behavior, inputs, and use case. An agent can select and invoke it without additional information.

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?

Although the schema describes projectId only as 'UUID проекта', the description adds semantic meaning by explaining that it optionally scopes the aggregate to a project. This makes the optional filtering behavior explicit despite the sparse schema text.

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

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

The description opens with a specific verb and resource: 'Aggregate statistics across all goals' and enumerates the exact metrics returned (total count, status breakdown, root count, blocked count, overdue count). This clearly differentiates it from sibling list/detail/mutation tools such as goal-list, goal-get, and goal-tree.

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

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

It explicitly states when the tool is appropriate ('Useful for daily standups and dashboard views') and indicates the scoping condition via projectId. It does not name excluded alternatives, but the intended use case is clear enough for an agent to select it over CRUD siblings.

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

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

Annotations already indicate a mutating, non-idempotent operation. The description adds useful behavioral specifics: priority defaults to 4 (low), 'suggestion' tag is auto-added, and project resolution falls back to default. No contradiction with annotations.

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

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

Two sentences, front-loaded with the core behavior, then defaults and fallback, closing with the sibling comparison. No filler or redundancy.

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

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

For a quick-capture creation tool with 5 parameters and no output schema, the description covers the key decision points: what it creates, defaults, project resolution, and when to prefer it over goal-create. It does not mention return value or duplicate behavior, but annotations already signal non-idempotency.

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 covers 100% of parameters with descriptions, so baseline is 3. The tool description adds minimal meaning beyond the schema (e.g., clarifies priority 4 as 'low'), but largely restates defaults already documented in the schema.

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

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

Description opens with a specific action ('Quick-capture a task or improvement idea') and names the resource (project/backlog task). It also differentiates itself from sibling goal-create, so an agent can choose correctly without inspecting schemas.

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 describes a lightweight alternative to goal-create with a clear condition ('when you need minimal ceremony'), which routes tool selection. It does not spell out negative cases, but the comparison is sufficiently clear.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds valuable behavioral context by disclosing the response shape — each node includes id, title, status, priority, type, progress, and nested children — and by explaining how projectId and rootId alter the scope of the tree. It stops short of details like ordering or progress format, but the added value is solid.

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

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

Three sentences, each earning its place: the core action, the optional filters, and the node shape. The primary purpose is front-loaded and there is zero 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?

With no output schema, the description compensates by specifying the exact node fields and nested structure. Both parameters are explained, defaults are implied, and the readOnlyHint annotation covers the safety profile. Only minor edge cases — such as behavior when both filters are supplied or the progress value format — remain 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 100%, so the baseline is 3, but the description still adds meaning by assigning each parameter a behavioral role: projectId 'scopes to one project' and rootId 'gets a subtree', which also implies the defaults (all projects, full hierarchy). This is richer than the terse schema descriptions.

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

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

The description opens with a specific verb and resource: 'Fetch the full goal hierarchy as a nested tree.' The emphasis on 'full' and 'nested tree' with a 'nested children array' clearly distinguishes it from flat-list siblings like goal-list and single-object siblings like goal-get.

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 filtering semantics ('scope to one project' vs 'get a subtree') provide clear context for when to narrow the call, and the first sentence states the primary use case. However, it never names alternatives such as goal-get or goal-list, nor states when not to use this tool, so the agent must infer selection from the tree-shaped requirement.

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

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

The description goes far beyond the annotations with outstanding behavioral disclosure: the partial-merge semantics, the full status transition matrix with its AC/red-team check gating, the attemptCommit side effects (post-deploy probes that record machine verdicts, repeated setting resets delivery marks and probes, '' clears), and the visual AC advisory flow that freezes the AC contract. However, there is a tension: the annotation declares idempotentHint=true, yet the description states that re-setting attemptCommit creates a new attempt and resets probes — non-idempotent behavior for that field. The description is transparent, but this inconsistency with the annotation could mislead an agent into unsafe retries.

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 core semantic is well front-loaded in the first sentence, and every sentence carries necessary information. However, the status transition matrix is an extremely dense run-on with nested conditionals (backlog→ready_for_work (author; grove: requires ≥1 AC, red-team check when the project requires it — the goal parks in checking_ac and becomes ready_for_work, checking_ac_failed or checking_ac_errored)). While information-dense, it is poorly structured and hard to parse, reducing readability despite containing no waste.

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

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

For a 12-parameter mutation tool with no output schema and significant side effects, the description is remarkably complete: it covers partial-update semantics, the full transition matrix with authorization and gating rules, attemptCommit's deployment-triggered probe behavior, the visual AC advisory and its resolution paths, rejected transitions, and the return value ('Returns the updated goal with all fields'). No critical information an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value on top: it explains the status parameter's transition constraints and who may perform them (author/executor), the dismissVisualAcSuggestion flag in the context of the ready_for_work advisory freeze, and attemptCommit's post-deploy probe semantics and clear-with-'' behavior. It also ties the visual AC suggestion to goal-add-criterion(visualEvidenceSuggested=true) as the alternative path. This is more than the per-field schema docs provide.

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

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

The description opens with a precise, specific statement of function: 'Partial update of a goal — only the fields you pass are changed; omitted fields are untouched.' This names the verb (update), the resource (goal), and the defining semantic (partial merge) that separates it from goal-create (full create) and goal-delete (destructive). It is immediately distinguishable from its many siblings.

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

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

The status transition matrix provides rich internal usage context — which transitions are allowed, who can perform them, and what checks gate them (backlog→ready_for_work requires ≥1 AC in grove mode; backlog→in_progress and backlog→done are rejected). However, it never explicitly routes the agent to alternatives: nothing says 'to create a goal use goal-create' or 'to change only status consider goal-block/goal-move.' The when-to-use is implied by the name and semantics rather than stated, and there are no exclusions naming sibling tools.

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

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

Annotations already signal mutability through readOnlyHint=false, and the description adds a meaningful behavioral boundary: status transitions are not manually permitted and depend on external evidence judge verdicts. This goes beyond the structured metadata and helps an agent reason about side effects and constraints. There is no contradiction with the annotations.

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

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

Two focused sentences with no filler. The core action is front-loaded, and the status limitation is stated immediately afterward in a separate sentence. Every word earns its place.

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

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

For a simple three-parameter update with complete schema descriptions and no output schema, the description covers the key operational constraint. It could have noted that text and signpost are optional and at least one may be required for a meaningful update, but the schema and current wording provide adequate context.

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

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

The input schema already fully documents all three parameters with descriptions for text, signpost, and assumptionId. The description does not add deeper semantics such as formatting requirements, field interactions, or minimum-field constraints, so baseline schema coverage is sufficient here.

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

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

The description opens with a specific verb and resource: 'Update text or signpost of an assumption.' This cleanly separates the tool from generic siblings like goal-update and goal-update-criterion by naming the exact editable fields and the target object. The added status limitation further clarifies what the tool is not for.

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

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

The description clearly states a when-not-to-use condition: status cannot be changed manually, and transitions come only via evidence judge verdicts. It does not name a specific alternative sibling tool, but the exclusion is explicit and actionable enough for an agent to avoid misusing this tool for status changes.

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 readOnly=false and idempotent=true; the description goes well beyond by explaining probeClass/probeSpec interaction, error cases (probe_required), probe dropping for pre-merge, mode-dependent linter blocking, and the return value. This gives the agent a realistic model of side effects and failure conditions.

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 dense but efficient: it front-loads the core purpose, then packs conditional behavior and return information into a compact paragraph. Every clause contributes meaning, though the structure is slightly run-on and could benefit from clearer separation of mode rules.

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

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

With no output schema, the description correctly supplies return value details (updated criterion fields and quality findings). It also covers error conditions, environment/mode constraints, and parameter interactions, making the tool fully actionable for an agent. Only an explicit sibling-tool comparison is absent, but that is not essential here.

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?

Although schema coverage is 100%, the description adds crucial cross-parameter semantics: probeSpec alone implies post-deploy, probeClass=post-deploy keeps an existing probe when omitted, pre-merge drops the probe, and missing required probes produce error=probe_required. These rules are not derivable from the individual parameter descriptions.

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

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

The description states a specific verb and resource: 'Update an acceptance criterion' and lists exactly what can be changed (text, class, probe). This clearly distinguishes it from sibling tools like goal-add-criterion and goal-remove-criterion without requiring the agent to infer intent.

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

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

The description gives clear context on when the tool applies: updating an existing acceptance criterion, and it details mode-specific conditions (Grove vs. Standard). It does not explicitly name alternative tools or say 'use this instead of X,' but the scope and conditional behavior are clear enough for an agent to select it appropriately.

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

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

Beyond the annotations (idempotentHint=true, readOnlyHint=false), the description reveals concrete behavioral details: idempotent calls return an already_existed=true flag, self-references are rejected, and no cycle detection is performed. This gives the agent accurate expectations for repeated calls and edge cases.

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

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

Four tight sentences, each carrying distinct information: core purpose, accepted identifiers, idempotency behavior, self-reference rejection, and cycle-detection limitation. The main action is front-loaded, and there is 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?

For a two-parameter tool with no output schema, the description is complete. It explains the operation, the accepted identifier formats, the idempotent return flag, the self-reference rejection, and the important caller responsibility regarding cycles. Nothing critical is missing for an agent 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?

Schema coverage is 100%, so the baseline is 3. The description adds the useful clarification that UUID or slug is accepted 'for both sides', but the parameter descriptions in the schema already document each parameter's meaning and role. No additional semantic depth beyond that is provided in the description.

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

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

The description opens with a specific verb and resource: 'Declare that one project depends on another (depends-on relationship)'. This unambiguously identifies the operation and is clearly distinct from the sibling project-remove-dependency, even without naming it. The relationship direction is further clarified by the parameter names and the explicit 'both sides' note.

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

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

The description clearly states what the tool does and adds practical usage boundaries: idempotent behavior, self-references rejected, and no cycle detection. The 'caller is responsible for avoiding circular chains' sentence gives explicit guidance about when this tool is not sufficient. It does not explicitly name alternatives, but the add-vs-remove distinction is obvious from the operation and sibling list.

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

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

Annotations only indicate this mutates and is not idempotent. The description adds significant value: it states the created project is returned with id, slug, and webUrl, and discloses that duplicate slugs are rejected with a list of existing slugs. This is exactly the kind of behavioral 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?

A single dense paragraph with no filler. The opening sentence states the core purpose, followed by requirements, optional fields, return value, and uniqueness behavior. Every sentence earns its place.

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

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

For a 10-parameter creation tool with no output schema, the description covers the required/optional split, defaults, slug constraints, duplicate handling, return fields, and nested sourceRef format. Combined with 100% schema description coverage, an agent has everything needed 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 coverage is 100%, so the baseline is 3. The description mostly restates schema constraints such as slug character rules, status options, and sourceRef shape rather than adding genuinely new semantics. It is a useful English summary of Russian schema descriptions, but it does not go beyond them substantively.

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: 'Create a new project container for goals.' The phrase 'container for goals' distinguishes it from goal-create and other goal-* siblings, and 'project-create' is clearly distinct from project-update, project-get, project-list, and project-delete.

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

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

Provides clear context: this tool is for creating a new project, with required fields and defaults. It does not explicitly name alternatives like project-update or goal-create or state when not to use it, so it stops short of full exclusion guidance.

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

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

Even though destructiveHint=true already flags the destructive nature, the description adds substantial context beyond annotations: the cascade-delete branch, the rejection failure mode with goals count, and the exact return payload (deleted title, slug, goals_deleted count). This is precisely the behavioral detail an agent needs to predict outcomes.

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 tightly structured sentences: purpose first, then the force conditional behavior, then the return values. No filler; every sentence carries unique information and the ordering front-loads the most important facts.

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

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

For a destructive tool with no output schema, the description covers the primary flow, the guard condition, and the return values — the last being essential since no output schema exists. Minor gaps remain: behavior on non-existent projects and repeated calls (relevant given idempotentHint=true), but nothing that would mislead an agent on the main path.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description reinforces force's role and adds one useful detail beyond the schema — the rejection return includes the goals count — but mostly restates what the schema's Russian descriptions already convey. Modest value added, slightly above the baseline 3.

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

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

The description opens with 'Delete a project' — a specific verb and resource — and then layers on the distinctive goal-cascade behavior. This makes it immediately distinguishable from siblings like goal-delete and account-delete, which operate on different resources.

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

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

The description provides clear conditional usage: pass force=true when goals exist to cascade, and warns that without force the call is rejected with the goals count. This effectively teaches the agent when to set force. It doesn't explicitly name sibling alternatives or exclusions, which is the only thing holding it back from 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=true, and the description does not contradict this. It adds meaningful behavioral context by detailing the returned shape, including the sourceRef null case and the goals-by-status breakdown, which helps the agent understand what the response will contain.

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

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

The description is a single, front-loaded sentence that uses a colon to introduce a structured list. Every listed field adds value, and there is no redundant or filler content.

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

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

With no output schema, the description carries the full burden of explaining the return value, and it does so thoroughly: all major fields, the sourceRef structure and null case, the goals counts, and the depends_on list. For a simple read-only getter, this is complete enough for an agent 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 100% and the single parameter projectId is already documented as a project UUID. The description adds no new information about the parameter itself, so the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Fetch' and clearly identifies the resource: full project details. It enumerates the returned fields in detail, which distinguishes this tool from project-list, project-update, and other siblings that operate on the same resource.

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

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

The intended use is implied by 'Fetch full project details' and the required projectId parameter, but the description does not explicitly state when to use this tool versus project-list for more summary-level information. No exclusions or alternative routing are provided.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds meaningful behavioral context by stating it returns all projects and listing the exact fields (id, title, slug, webUrl, icon, goals_count), which is especially valuable given there is no output 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 concise sentences accomplish everything: the main behavior, the optional parameter, the return fields, and a pointer to the alternative tool. No filler or redundant information is present.

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

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

For a simple read-only list operation with one optional parameter, the description is complete. It covers the full request semantics, the response contents, and the sibling tool to use when more detail is needed.

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

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

Schema description coverage is 100% for the single optional status parameter, and the schema already documents the allowed values (active/archived/paused). The description merely repeats this filter concept without adding syntax, formatting, or behavioral details beyond the schema.

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

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

The description clearly states the tool's action ('List all projects') and resource, and specifies the optional status filter and returned fields. It distinguishes itself from project-get, which is a sibling tool for full details, so an agent can easily tell them apart.

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

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

The description provides explicit guidance on when to use an alternative: 'Use project-get for full details with goals breakdown by status.' This tells the agent that project-list is for summarized lists, while project-get is for deeper detail.

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

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

Annotations already indicate this is a mutation (readOnlyHint=false) and idempotentHint=true. The description adds useful behavior beyond that: the not-found case returns removed=false rather than an error, and the success return flag is described. No contradiction with the annotations.

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

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

Two sentences carry all essential information: the action, the two valid call patterns, and the return behavior. There is no filler, tautology, or redundant restatement of the schema.

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

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

For a simple mutation with mode-dependent parameters and no output schema, the description covers the meaningful cases: success, not-found, and both lookup strategies. It could have explicitly warned against invalid or incomplete argument combinations, but the 'pass X or pass both Y and Z' wording largely covers that.

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 descriptions already cover all three parameters, so the baseline is 3, but the description adds a clear mapping between parameters and the two lookup modes, plus return semantics. It clarifies that dependencyId is the UUID of the link itself and that projectId/dependsOnProjectId accept UUID or slug, though it uses dependency_id while the schema uses dependencyId.

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

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

The description opens with a specific verb+resource ('Remove a project dependency') and clearly identifies the target as a dependency link, distinguishing it from project-delete and goal-remove-* tools. The two-lookup-mode explanation further clarifies exactly what entity is being removed.

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 concrete usage directions for both lookup modes and states the condition for each: pass dependencyId, or pass both projectId and dependsOnProjectId. It does not explicitly name alternatives like project-add-dependency, but the resource-specific naming makes the intended use obvious.

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, idempotentHint=true), the description discloses the key behavioral trait that unmentioned fields are not reset, returns the updated project with all fields, and warns about sourceRef/clearSourceRef incompatibility. This adds meaningful semantic context for a mutation operation.

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

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

The core semantic is front-loaded in the first clause, and the rest is a dense enumeration of all 19 updatable fields with their valid values. It is a long single sentence, which is somewhat hard to scan, but for a tool with 19 parameters it is information-efficient and avoids 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?

Given there is no output schema, the description correctly states that the tool returns the updated project with all fields. It also covers every parameter's valid values, the nested sourceRef object shape, the clearSourceRef incompatibility, and partial-update semantics. An agent has enough information to invoke the tool correctly across all documented 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?

Schema coverage is 100%, so the input schema already describes every parameter in detail. The description does add value by enumerating valid values for enum-like parameters (e.g., status, redTeamMode, escalationResolveTimeout) and repeating the sourceRef shape, but this mostly mirrors the schema rather than adding substantial new meaning. Baseline 3 is appropriate.

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

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

The description starts with a precise verb and resource: 'Partial update of a project'. It clearly distinguishes this from sibling tools like project-create, project-delete, and project-get by emphasizing that only passed fields are changed while omitted fields remain untouched. This is a specific, unambiguous purpose.

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

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

The description clearly establishes when this tool should be used: when you need to update a project partially. It also provides an important exclusion by noting that clearSourceRef is incompatible with sourceRef. However, it does not explicitly mention alternatives or state 'do not use for creating/deleting projects', though the sibling names make that inferable.

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