Planner (proof-of-done)

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

Beyond the destructiveHint annotation, the description adds critical behavioral details: irreversibility, the full scope of data deletion (projects, goals, evidence, history), and the two-step safeguard mechanism (first call triggers warning/challenge, second call requires confirmations). This substantially enhances the agent's understanding of the tool's behavior and risks.

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 concise sentences, front-loaded with the most critical warning about irreversibility and data scope, followed by the two-step process and a caution. Every sentence adds value with no redundancy or filler.

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

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

Given that the tool is destructive, has no output schema, and has 5 optional parameters, the description adequately covers irreversibility, data scope, the safeguard sequence, and the requirement for explicit user request. It does not spell out the exact content of the challenge/warning, but the schema descriptions for parameters like reasoning_answer and confirm_passphrase partially fill that gap. The description is complete enough for safe and 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?

The schema already provides 100% description coverage for all 5 parameters, so the baseline is 3. The description adds meaningful context by explaining that parameters are intended for the second call and that reasoning_answer and confirm_passphrase originate from the first call's challenge. This clarifies the sequential usage of parameters beyond their individual schema descriptions.

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

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

The description clearly states the tool's purpose: 'Irreversibly delete your account and ALL data (projects, goals, evidence, history).' It uses a specific verb (delete), identifies the resource (account plus all associated data), and distinguishes this from sibling tools like goal-delete and project-delete, which target individual entities.

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 says 'Do NOT call without explicit user request', providing a clear when-not-to-use rule. It also describes the two-step process (call without arguments first to get a warning/challenge, then call again with confirmations), which gives strong context for how to use the tool. However, it does not explicitly name alternative tools for less destructive operations, so it misses the 'alternatives' criterion by a narrow margin.

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 several behavioral traits beyond annotations: the assumption is an explicit premise, text must pass a linter, and type is auto-classified by an LLM. It also implies mutation, consistent with readOnlyHint=false. No contradiction with annotations.

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

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

The description is three concise sentences, front-loaded with the primary action and elaborating on constraints and behavior. Every sentence adds essential context with no redundant wording.

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 write tool with no output schema, the description covers the action, target resource, prerequisites, validation constraint, and auto-classification behavior. It is complete enough for an agent to select and invoke correctly, aided by rich annotations and 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 coverage is 100%, setting a baseline of 3. The description adds value by explaining the purpose of the text parameter (explicit premise) and the 'parent→child' relationship for goalId, which enriches understanding beyond the schema's Russian descriptions.

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

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

The description clearly states the action: 'Add an assumption to a goal edge (parent→this goal)'. It specifies the exact resource (goal edge) and the direction (parent→child), which distinguishes it from siblings like goal-add-criterion or goal-remove-assumption.

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

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

The description provides explicit usage conditions: 'Requires the goal to have a parent (root goals have no edge)' and mentions the text must pass a quality linter. While it doesn't name alternatives, the when/when-not conditions are clearly stated.

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

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

Annotations already indicate non-read-only and non-idempotent, but the description adds significant context: Grove mode's 'frozen once started' rule, linter blocking behavior, and advisory linter in Standard mode. It also discloses the return structure, going beyond the annotations.

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

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

The description is three sentences, each serving a clear purpose: the action, the text constraint, then mode/return behavior. It is front-loaded and contains no filler.

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

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

Given the tool's mode-dependent complexity and lack of an output schema, the description covers essential constraints and return values. However, it leaves ambiguity about whether additions are permitted in Standard mode after goal closure, only stating that ACs are editable until then.

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 100% schema coverage, the baseline is 3, but the description elevates this by constraining the 'text' parameter to require an observable check over an artifact, which is absent from the schema's generic 'Формулировка критерия'. This adds meaningful 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 'Append an acceptance criterion to a goal,' a specific verb and object that clearly distinguishes this from sibling tools like goal-add-assumption or goal-update-criterion. The mention of the return values further reinforces its unique 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 provides mode-specific usage rules (Grove vs Standard) and explains when additions are allowed relative to goal state. It does not explicitly name alternative tools, but the constraints imply this is for adding rather than updating or removing criteria.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses that this tool does NOT close an acceptance criterion and that plain evidence is only a complement. This is critical behavioral context not present in the annotations and clearly defines the tool's role and limitations.

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 moderately concise and front-loads the key distinction with 'SUBORDINATE / supplementary path'. While longer than the two-sentence ideal, every sentence provides necessary caveats about scope and exclusions, with no fluff.

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

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

The description fully covers the tool's purpose, its relationship to the key sibling goal-attach-evidence, and the constraints on valid input. It is complete for a supplementary tool with no output schema, leaving no ambiguity about how to use it.

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

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

Schema description coverage is 100%, and the schema already documents 'text' as a URL or manual scenario. The description adds exclusions ('NOT for bytes', 'NOT for filesystem paths') but these are more about usage boundaries than new parameter semantics. Thus, the baseline of 3 is appropriate.

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

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

The description opens with 'SUBORDINATE / supplementary path' and clearly states the tool adds a text-only note as extra context. It explicitly distinguishes from goal-attach-evidence, which actually closes an AC, making the purpose unambiguous.

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

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

The description explicitly instructs to use goal-attach-evidence for every criterion and provides clear exclusions: 'NOT for bytes' (screenshots, logs, API responses, exports) and 'NOT for filesystem paths'. It also states that plain evidence never counts toward AC coverage, giving decisive when-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 indicate it's a write operation (readOnlyHint false). The description adds that notes are not evidence, are visible in the detail panel, and returned by goal-get under notes[]. It does not cover all potential behaviors (e.g., no mention of editing or deletion), but provides sufficient context for an additive tool.

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

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

The description is two sentences with no unnecessary words. The main action is front-loaded, followed by essential clarifications. Every sentence serves a purpose.

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

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

Given low complexity (2 params, no output schema), the description fully explains the tool's role, behavior, and relationship to siblings. It mentions visibility and retrieval via goal-get, which is sufficient context.

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

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

Schema coverage is 100% and already describes both parameters (text as markdown string, goalId as UUID). The description reinforces that notes are free-form and markdown supported, but adds minimal new semantic value beyond the schema.

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

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

The description clearly states the action (add a free-form note), resource (to a goal), and format (markdown supported). It distinguishes from the sibling tool goal-attach-evidence by noting that notes are not evidence and do not count toward acceptance criteria coverage.

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 (for decisions, dead ends, context) and when not to use (for evidence, directing to goal-attach-evidence). It also clarifies that notes do not affect AC coverage or closing a goal, preventing misuse.

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 richly discloses behavioral traits: exact status transition rules (supports → supported, first challenge → challenged, repeated challenge → invalidated), terminal nature of invalidated, and fail-open behavior on judge infra failure. Annotations only provide readOnlyHint=false and idempotentHint=false, so the description adds substantial context beyond those fields.

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

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

The description is three sentences long and packs essential behavioral information without fluff. It front-loads the primary action and is appropriately concise for the complexity involved.

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 thoroughly explains side effects and state transitions, and mentions the failure mode. Since there is no output schema, the absence of an explicit return-value description is a minor gap, but the operational outcome is clear enough for most agents.

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 both parameters (text and assumptionId) with 100% coverage, so the description does not need to add parameter-level meaning. It does add context about how the text is judged, but not syntax or format 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 uses a specific verb 'attach' and identifies the resource 'text evidence to an assumption', further clarifying with the judging behavior. It clearly distinguishes from the sibling goal-attach-evidence by focusing on assumptions and the automatic status transitions.

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

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

The description implies usage context: attach evidence to an assumption and judge it. However, it does not explicitly state when to prefer this tool over alternatives like goal-attach-evidence or goal-add-evidence-text, nor does it provide any exclusions or when-not-to-use guidance.

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

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

Even though annotations provide readOnlyHint=false and idempotentHint=false, the description discloses crucial behavioral traits: the MCP base64 path is unreliable for non-trivial files (with measured evidence of truncation), contentSha256 is needed for fast-fail integrity, and server-side MIME/size validation exists. It also explains that the server returns an evidence record plus file URL, fully consistent with the write operation.

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

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

The description is extremely long, including a shell recipe, measured failure examples, and multiple fallback paths—valuable but far from concise. It is front-loaded with the core purpose and clearly structured with headings and bullets, which aids scannability, but there is redundancy (e.g., repeated warnings about base64 unreliability) and several sentences are auxiliary rather than essential.

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

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

Given the complexity (8 parameters, multiple transport options, no output schema), the description is remarkably complete. It covers validation rules (MIME whitelist, size caps, quota), error handling (file_hash_mismatch), return shape (evidence record + file URL + serverSha256), and even provides alternative invocation methods. This fills all gaps left by the missing output schema.

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

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

Schema coverage is 100%, but the description adds substantial semantics: contentBase64 is risky for large files, contentSha256 is the primary defense against truncation, kind is restricted to `session_history` and does not cover an AC, and caption should state reproduction conditions. This enriches the parameter meaning well beyond raw schema definitions.

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 specific purpose: 'Attach binary evidence ... to an AC' and emphasizes it is 'the ONLY tool that covers an acceptance criterion.' It explicitly differentiates from the sibling goal-add-evidence-text, which 'does NOT cover an AC,' making the tool's role 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?

The description gives explicit when-to-use guidance: for files > ~1 KB raw it directs to goal-request-upload or planner-attach.sh, while for ≤ ~1 KB it says 'this MCP tool is fine.' It also distinguishes when to prefer goal-add-evidence-text for non-binary context, and provides a copy-paste recipe and fallback endpoints—far beyond minimal guidance.

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

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

Beyond the annotations (readOnly=false, idempotent=false), the description discloses key behavioral traits: additive behavior (each call appends, existing blockers preserved), status change to blocked, the mutual exclusivity of resolver options, and the status-revert mechanism when all blockers are removed. This adds substantial context that 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?

The description is four sentences, each carrying distinct, necessary information: main action, status change, optional resolver behavior, and removal lifecycle. There is no redundancy or filler; it is front-loaded with the primary purpose and efficiently covers the key nuances.

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

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

The description covers the core aspects for a tool with 6 parameters and no output schema: additive semantics, status side-effect, resolver creation/linking options, and the effect of removal. It does not mention edge cases like what happens if the goal is already blocked or whether the resolver goal persists after blocker removal, but these are minor relative to the overall completeness.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the mutual exclusivity of resolverTitle and linkedGoalId, and clarifying that resolverParentId defaults to goalId (making the resolver a child). It also ties the overall additive behavior to the call semantics, enriching parameter understanding.

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

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

The description opens with 'Add a blocker to a goal', combining a specific verb with a clear resource. It distinguishes this from sibling tools like goal-add-note or goal-add-assumption by explicitly focusing on blockers and their additive, status-changing behavior.

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: blockers are additive, each call appends a new one, and the goal's status is set to blocked. It also mentions the complementary tool goal-remove-blocker and the effect of removing the last blocker, guiding lifecycle usage. It does not explicitly state when NOT to use it, but the guidance is sufficient for this mutation tool.

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

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

Annotations only indicate non-readonly and non-idempotent. The description adds substantial behavioral detail: grove mode enforces acceptance criteria before in_progress and file-evidence per AC before done, while standard mode uses advisory linting. It also discloses the return payload (id, webUrl, mode, nextStep hint). No contradiction with annotations.

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

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

The description is four sentences, front-loaded with the purpose, followed by mode details, return information, and a key constraint. Every sentence adds value and there is 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?

Given the tool has 12 parameters and no output schema, the description does a thorough job: it explains the two modes, the acceptance criteria gate, the project requirement, and the returned fields. The schema handles parameter-level details, and the description ties the high-level behavior together.

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 met. The description goes beyond the schema by explaining the behavioral meaning of the mode parameter and clarifying the relationship between projectId and parentId for project membership.

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 'Create a goal/task/milestone/habit in the planning tree' with a specific verb and resource. It also distinguishes the tool by describing the two modes (grove vs standard) and the project requirement, which sets it apart from 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 provides clear context for when to use the tool and explains mode selection (grove default vs standard), including behavioral consequences. It also calls out the important prerequisite that every goal must belong to a project. However, it does not explicitly mention alternatives or when-not-to-use scenarios relative to sibling tools like goal-update.

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 include destructiveHint=true, but description adds cascade behavior ('all its descendants') and return value ('Returns the deleted title and children_deleted count'). This goes beyond the structured data.

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

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

Three sentences, front-loaded with the most critical information (irreversible, cascade). No unnecessary words; 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 destructive cascading delete with no output schema, the description fully explains scope, behavior, return value, and when to avoid use. Very complete for the tool's complexity.

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

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

The schema has one required parameter goalId with a description ('UUID цели'), covering 100% of parameters. The tool description does not add further parameter-specific detail, so baseline 3 is appropriate.

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

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

Description states a specific verb and resource: 'IRREVERSIBLY delete a goal and all its descendants (children, evidence, blockers).' This clearly distinguishes the tool from siblings like goal-update and goal-block.

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 provides alternatives and when to use: 'Prefer goal-update status=cancelled to preserve history, or goal-block to mark an obstacle. Use delete only for erroneous/duplicate entries.' This is excellent 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 declare idempotentHint=true, and description adds that the dismissal is recorded in history and surfaced in goal-get, providing context beyond the structured annotations.

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

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

Three concise sentences, front-loaded with purpose, no wasted words. Every sentence adds distinct value.

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

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

Given the tool's simplicity, the description fully covers purpose, constraints, behavioral effects, and alternative actions. No gaps identified.

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, and description adds meaning by specifying the reason must be at least 80 characters and explaining where it appears in history.

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?

Clearly specifies the verb 'dismiss', resource 'red-team finding', and condition 'when you disagree with the verdict'. Distinguishes from sibling tools like goal-add-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?

Explicitly prefers goal-add-criterion over dismissing, and requires a reason of at least 80 characters. Implicitly guides when to use (disagree with verdict) but does not list exclusions.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds value by enumerating the full set of returned fields (children, acceptance criteria, history log, etc.), giving the agent a clear picture of what to expect beyond the bare annotation.

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: the first lists return fields, the second gives usage context. No redundant fluff, every phrase carries meaning, and the structure is front-loaded with the core purpose.

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

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

Given there is no output schema, the description compensates by listing all major return fields and providing context for when to use the tool. It could be slightly more explicit about error handling or the shape of nested children, but for a single-parameter read tool this is quite 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?

The schema has 100% coverage with a description for goalId (UUID цели). The tool description adds little beyond what the schema already provides, but it doesn't conflict or cause ambiguity; the parameter semantics are adequately handled by the schema.

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

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

The description clearly states the tool fetches full details of a single goal and enumerates the exact fields returned (title, description, status, etc.). It also distinguishes itself by naming the preceding tools (goal-list, goal-tree) and calling itself the 'primary drill-down 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 explicitly says when to use this tool: 'after goal-list or goal-tree' and labels it the 'primary drill-down tool'. This provides clear context, though it doesn't mention explicit alternatives or when-not-to-use scenarios.

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 key behavioral traits beyond the readOnlyHint annotation: pagination behavior (no offset, max limit), sort order (priority ASC, createdAt DESC), and the 'direct children only' restriction for parentId. It also lists the exact return fields, which is valuable given 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?

The description is two sentences, front-loaded with the core purpose ('List goals'), followed by precise filter and behavior details. Every word contributes meaning with no redundancy.

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

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

For a read-only list tool with no output schema, the description is highly complete. It covers filters, pagination, sorting, and return fields. It does not require additional context to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by consolidating parameter meanings in English (schema is partly Russian), clarifying 'direct children only' for parentId, and highlighting the default limit of 50. This goes slightly beyond the schema's raw field descriptions.

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

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

The description clearly states 'List goals with optional filters', specifying the exact operation and resource. It distinguishes from siblings like goal-get (single item) and goal-tree (hierarchy) by focusing on a flat list with filters.

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

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

The description gives clear context for use: listing goals with optional filters, limit, and sorting. It does not explicitly compare to alternatives (e.g., goal-get) but implies its role as a list endpoint. No exclusions or alternative tool names are mentioned, so it stops short of a 5.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description reveals important behavioral traits: 'Cascades project change to all descendants' and 'Prevents cycles.' It also explains inheritance behavior, adding meaningful safety and side-effect context.

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

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

The description is front-loaded with the core purpose and uses compact clauses for each usage mode. Every sentence adds essential detail—reparenting, root moves, cross-project overrides, cascading, and cycle prevention—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 mutation tool with no output schema, the description covers the primary decision points: what the tool does, how to invoke each mode, the side-effect of cascading project changes, and a safety guarantee. The required goalId is documented in the schema, so completeness is adequate.

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 descriptions cover all three parameters, the description goes further by explaining the interactions: how newParentId and projectId combine, when projectId is used, and that moving under a new parent inherits that parent's project. This adds meaningful semantics beyond the schema.

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

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

The description opens with a specific verb and resource: 'Move a goal to a different parent or project.' It details the two modes (reparenting vs. making root) and the cross-project option, which differentiates it from sibling tools like goal-reorder or goal-update.

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 explicit usage patterns: 'newParentId=UUID to reparent', 'newParentId=null to make root', and 'projectId=UUID overrides' for cross-project root moves. It doesn't name sibling alternatives or exclusions, but the context is clear enough to select this tool.

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

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

Annotations already declare readOnlyHint=true, making the read-only nature clear. The description adds value by specifying the return format (enriched records with fields) and the freshness window based on createdAt. It does not describe auth/rate limits or the 'неосновное окно' concept, but for a read-only list tool this is adequate. No contradiction with annotations.

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

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

The description is compact, with a clear parameter list appended. It front-loads the purpose and then specifies parameters. However, the phrase 'неосновное окно' is jargon that may confuse an agent, and the structure could be slightly more direct.

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

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

For a simple read-only list tool, the description covers purpose, parameters, and return fields. It explains the filtering scope (project, withinDays, statuses) and the enriched output. Missing details include error conditions and the meaning of 'неосновное окно', but overall it is sufficient for an agent 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?

The schema covers 100% of parameters, each with descriptions that match the tool description (project slug, withinDays window, statuses subset, limit). The description repeats the same defaults and allowed values without adding new semantic meaning beyond what the schema already provides. Therefore, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns enriched records (title/description-preview/parent/counts) for selecting items without calling goal-get, scoped to one project, a time window, and statuses. It distinguishes itself from goal-get by explicitly mentioning that alternative is not needed. The phrasing 'pull-inbox' is slightly metaphorical but the core action (list recent unresolved items) is clear.

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 provides clear context: use this tool to pick up and work on items by project, within N days, and with certain statuses. It names goal-get as an alternative to avoid, which helps with tool selection. However, it does not explicitly state when not to use this tool versus sibling tools like goal-list or goal-todo, so exclusions are missing.

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

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

Annotations already indicate it is a write operation (readOnlyHint=false) and idempotent (idempotentHint=true), but the description adds no additional behavioral context such as side effects, error handling, or what happens if the assumption does not exist. It simply restates the action without disclosing any traits beyond the annotations.

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

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

The description is a single sentence that directly states the action, with no superfluous information. It is appropriately concise for a simple tool.

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

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

The tool has a single parameter, no output schema, and is a straightforward removal operation. However, the description does not explain what a 'goal edge' is or what response to expect, nor does it mention any special cases. It is adequate but leaves some context 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 covers 100% of the parameter (assumptionId is described as 'UUID допущения'), so the description does not need to add parameter details. The description itself does not elaborate on the parameter meaning or format, but the schema is sufficient.

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

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

The description uses the specific verb 'Remove' with a clear object ('an assumption') and context ('from a goal edge'), distinguishing it from sibling tools like goal-add-assumption and goal-update-assumption. It unambiguously states the tool's 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 provides no guidance on when to use this tool versus alternatives such as goal-update-assumption or goal-remove-criterion, and does not mention any prerequisites or exclusions. The only usage context is implicit from the purpose.

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

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

The description goes beyond the annotations (readOnlyHint=false, idempotentHint=true) by explaining specific side effects: the automatic status reversion to 'in_progress or backlog' if the last active blocker is removed, and the non-deletion of a linked resolver goal. This adds valuable behavioral context 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 composed of two concise, front-loaded sentences. The first sentence states the core action, and the second provides essential side-effect information. No redundant or filler content 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?

Given the tool's simplicity (2 parameters, no output schema), the description adequately covers the main function, side effects, and an important caution about the resolver goal. It does not explain error handling or return values, but these are not critical for a straightforward remove operation with good annotations.

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

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

Schema description coverage is 100%, with both parameters already described (goalId and blockerId). The description adds minimal new semantic value by specifying that blockerId is a UUID, but this is a minor clarification. Baseline 3 is appropriate since the schema already carries the parameter meaning.

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

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

The description clearly states the verb 'Remove' and the resource 'blocker from a goal', specifying the method 'by blocker UUID'. It also differentiates from sibling tools like goal-remove-assumption or goal-remove-evidence by focusing on blockers. The additional detail about status change further clarifies its distinct 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 implies usage for removing blockers from goals but does not explicitly state when to use this tool over alternatives or provide exclusions. It lacks direct comparison with sibling tools like goal-block or other remove tools, so guidance is only implicit.

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

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

Annotations already declare destructive and idempotent behavior. The description adds important context: the removal cascades to all evidence on the criterion and returns confirmation with removed criterion details, which goes beyond the annotation-only picture.

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

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

Three sentences, each carrying distinct information: action, mode restrictions, and cascade/return. 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 tool with no output schema, the description covers the action, validity window, side effects, and response. This suffices for an agent to correctly invoke it.

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

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

The schema already fully describes criterionId as a required UUID. The description adds no additional parameter-specific meaning, so baseline 3 applies given 100% 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?

Description clearly states 'Remove an acceptance criterion from a goal' with a specific verb and resource. It distinguishes from sibling remove tools by targeting criteria specifically, and correctly contrasts with goal-update-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?

Provides explicit timing constraints: in Grove mode only while goal is in backlog (frozen once started), and in standard mode until goal is done. This gives when/when-not context, though it doesn't name alternative tools for other object types.

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

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

The description adds valuable behavior beyond the readOnlyHint=false annotation: it states that both the database record and the attached file are removed. It also explains the freeze-after-close rule, which is extra context. 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 concise sentences. The first states the main action; the second adds constraints and side effects. No fluff, and the most important information is front-loaded.

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 deletion tool, the description covers the core operation, the side effect (file deletion), and a key constraint. It is sufficient for an agent to select and invoke correctly. It omits error handling details, but these are not essential given the simple scope.

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

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

Schema covers the single parameter evidenceId with description 'UUID evidence-записи'. Tool description repeats 'by UUID' but doesn't add new meaning. Baseline 3 is appropriate as schema coverage is 100%.

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

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

The description clearly states the action: 'Delete an evidence record by UUID.' The verb is specific and the resource is well-defined, distinguishing it from sibling tools like goal-add-evidence or 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?

There is a clear condition: 'Forbidden if the owning goal is already done (evidence is frozen after close).' This tells the agent when not to invoke the tool. However, it does not explicitly mention alternative tools for similar operations, though the action is unique 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?

Annotations already indicate destructive and idempotent behavior. The description adds that the operation only deletes the note and does not touch other related items, providing specific behavioral context beyond the annotations.

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

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

Two concise sentences: first states the action and parameters, second clarifies scope. No redundant words or unnecessary detail.

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

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

For this simple two-parameter tool without output schema, the description covers the purpose, parameter origin, and behavioral scope. Combined with annotations, it provides complete guidance for an AI agent.

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

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

The input schema has 100% coverage with descriptions for both parameters. The description supplements by explaining that note ids come from goal-get, adding practical context for the noteId parameter without repeating schema details.

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 ('Remove') and a resource ('note from a goal'), and clearly distinguishes from sibling removal tools (e.g., goal-remove-assumption) by stating it never touches acceptance criteria, evidence, or blockers. It also specifies the identifier format (note UUID) and where to obtain it (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 description tells when to use the tool (when you have a note UUID from goal-get) and what it does not affect (acceptance criteria, evidence, blockers), implicitly guiding against using it for those purposes. However, it does not explicitly mention when not to use it or provide alternative tools for other cases.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true, so the write nature and idempotency are covered structurally. The description adds genuine behavioral value by disclosing that each goal is assigned position = its array index and that all goals must share the same parent and priority. It leaves edge cases undisclosed (e.g., behavior for goals omitted from the array), but the core mechanics are transparent.

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 tightly focused sentences: purpose first, then operational mechanics, then constraint. Every sentence earns its place with no filler or repetition of schema content.

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

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

For a single-parameter tool with annotations and no output schema, the description covers the essential behavior, the parameter mechanics, and the critical constraint. The only gap is the lack of detail on edge cases like omitting goals from the array or error behavior when the shared-parent/priority constraint is violated, which would round it out.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by defining the positional semantics—'each is assigned position = its array index'—which clarifies exactly how the ids array is interpreted beyond the schema's 'in new order' phrasing.

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 ('Set') with a precise resource ('display order of sibling goals within the same parent and priority band'), clearly distinguishing it from siblings like goal-move (which moves goals across parents) and goal-update. The scope constraint (same parent and priority) is explicit and unambiguous.

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

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

The description clearly conveys when to use this tool—reordering sibling goals within a shared parent and priority band—by stating the operation and its prerequisite constraint. However, it does not explicitly name alternatives or state when not to use it relative to goal-move or goal-update, so it stops short of full exclusionary guidance.

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

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

With minimal annotations (readOnlyHint=false, idempotentHint=false), the description carries the transparency burden and does well: it discloses the LLM judge evaluation, the pass-triggered escalation, and the allowed owner resolutions. It omits the failure outcome (e.g., rejection) and any side effects on evidence attempts, which is a minor gap.

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 three-sentence description is dense yet well-structured: purpose first, then requirements, then process/constraints. It uses efficient language without redundancy, though it could be trimmed slightly without losing meaning.

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

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

For a moderately complex tool with no output schema, the description explains the trigger, evaluation, and successful outcome, along with mode/state constraints. It does not describe failure behavior or return format, but overall it provides sufficient context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with both parameters clearly described, so the baseline is 3. The description adds marginal value by noting the reason will be judged for substantiality, which hints at how to craft it, but it does not materially extend the schema's parameter explanations.

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

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

The description clearly states it requests a change to an acceptance criterion that appears unreachable, with a specific verb and resource. It distinguishes itself from direct edit tools like goal-update-criterion by framing this as an escalation request, and the additional context about the LLM judge and escalation further clarifies its 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?

It gives explicit preconditions for use (≥3 failed evidence attempts with 0 matches) and operational constraints (Grove mode only, goal must be in_progress). It does not explicitly name alternative tools like goal-update-criterion for direct edits or goal-resolve-escalation for the owner's response, so it's clear but lacks formal when-not-to-use guidance.

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

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

The description discloses critical behavioral traits: the URL is one-time and expiring, the file must be streamed via PUT (not base64/token), and non-2xx responses mean rejection with no evidence created. It also details the response format and the optional SHA-256 header for integrity. This far exceeds the minimal annotations (readOnly=false, idempotent=false) by explaining the exact workflow and failure 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?

The description is long but well-structured, opening with a purpose statement and flowing into usage instructions with curl examples. Every sentence adds value—covering the upload protocol, optional integrity check, response format, and failure handling. It is front-loaded and free of filler, making it appropriate for the tool's complexity.

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

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

Despite having no output schema, the description fully covers the request-response lifecycle: how to obtain the upload URL, how to perform the PUT, what the response contains, and how to handle rejection. It also clarifies the relationship to sibling evidence tools. This is a complete guide for using the tool correctly.

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

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

The input schema already provides descriptions for all four parameters (100% coverage), so the baseline is 3. The description adds context around criterionId (acceptance criterion scoping) and the overall file-streaming flow, but does not add new per-parameter meaning beyond the schema. Thus a 3 is appropriate.

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

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

The description clearly identifies the tool as the preferred method for attaching large binary evidence files to acceptance criteria, explaining it returns a one-time upload URL and requires a PUT. It distinguishes itself from sibling tools (goal-attach-evidence, goal-add-evidence-text) by targeting non-trivial files. This is a specific verb+resource+scope.

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

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

The description explicitly states when to use this tool ('Use this instead of goal-attach-evidence for any non-trivial file') and when not to ('Use goal-add-evidence-text only for byte-less context'). It also names alternatives and explains why they are not suitable, providing clear decision criteria.

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

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

Beyond the readOnlyHint=false and idempotentHint=false annotations, the description openly discloses a critical side effect: all prior evidence on the AC is deleted for edit/split/drop, forcing fresh proof. This is exactly the kind of behavioral detail needed.

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

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

Two dense sentences, front-loaded with the verb and resource. No filler; every phrase carries meaning—modes, deletions, and the reject fallback are packed 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?

For a mutation tool with no output schema, the description covers the essential context: resolution modes, the destructive evidence deletion, and the reject path. The input schema handles parameter details, so the description is complete for safe 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 83% and includes descriptions for newText and linkedGoalId. The description adds semantic meaning for the resolution parameter (explaining what each value does) and clarifies the audit reference purpose, which the schema does not fully convey. overrideResolvedBy remains undocumented in both.

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

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

The description clearly states the action: 'Resolve a pending AC escalation' and enumerates the four resolution modes (edit, split, drop, reject). It distinguishes itself from sibling goal tools by focusing on the escalation workflow.

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 on when to use: when a pending AC escalation needs resolution and the caller acts as owner. It does not explicitly exclude alternatives or name sibling tools, but the resolution modes give implicit 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?

Beyond the read-only and idempotent annotations, the description discloses that the output is LLM-generated, includes 2-4 assumptions with signposts and type classification, and requires author review/editing before acceptance. This adds important behavioral context not captured by the annotations.

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

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

The description is two sentences, front-loaded with purpose, then output format, then next-step guidance. Every sentence earns its place with no redundancy or fluff.

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

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

For a simple read-only suggestion tool with one parameter, full schema coverage, and annotations, the description is complete. It explains what it returns (2-4 assumptions with signposts and type classification) and the required human-in-the-loop workflow, so the agent can determine when and how to use it effectively.

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 fully describes the only parameter (goalId with description 'UUID цели (ребёнка)'). The description adds no new information about the parameter itself; the parent→child context is already contained in the schema's 'ребёнка' (child) note. Thus the baseline of 3 applies.

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

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

The description states a specific action: 'LLM generates suggested assumptions for a goal edge (parent→child).' It clearly identifies the resource (assumptions for a goal edge) and distinguishes itself from sibling tools like goal-add-assumption, which actually adds assumptions rather than suggesting them.

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

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

The description provides clear workflow context: 'Author should review, edit, and accept relevant ones via goal-add-assumption.' This tells the agent that this tool is for generation, and the follow-up action belongs to a different tool. However, it does not explicitly state when not to use this tool or compare it to other alternatives like goal-update-assumption.

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 readOnlyHint=true, the safety profile is already covered. The description adds scoping behavior (all goals vs projectId) and the specific metrics computed, which is useful context. It does not mention performance or edge cases, but for a read-only summary tool this is acceptable.

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 redundant wording. The first sentence front-loads the action and specifics; the second gives a practical use case.

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 summary tool with one optional parameter and no output schema, the description covers the functional scope and statistics returned. It could mention the return format, but the listed metrics suffice 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?

The schema covers projectId with a description, and the description clarifies that null includes all goals while a projectId scopes the aggregation. This adds behavioral meaning beyond the schema's syntactic description.

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

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

The description clearly identifies the tool as an aggregation function over goals, listing specific metrics (total count, status breakdown, root count, blocked count, overdue count). This distinguishes it from sibling tools like goal-list and 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?

Provides a clear use case ('daily standups and dashboard views') and notes the optional projectId scoping, implying when it is useful. Does not explicitly exclude alternatives or name sibling tools, but the context is sufficient.

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 write operation (readOnlyHint: false) and non-idempotency (idempotentHint: false). The description adds concrete behaviors: priority defaults to 4 (low), auto-adds the 'suggestion' tag, and resolves project by slug with fallback to default project. It does not disclose error behaviors or return values, but the core side effects are covered.

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

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

Two sentences, front-loaded with the main action, and no redundant filler. The second sentence packs the defaults and differentiation 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?

For a 5-parameter creation tool with no output schema, the description covers the main behavioral contract (defaults, tag, project resolution) and differentiates from the sibling. It omits return-value details and failure cases, but those are not critical given the simplicity. Overall it is complete enough for an agent to 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 description coverage is 100%, with each parameter already described in Russian (e.g., priority default 4, project slug fallback, tags auto-add suggestion). The description mostly repeats these facts in English, adding only the semantic label 'low' for priority 4. Thus it adds minimal value beyond the schema.

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

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

The description uses a specific verb ('Quick-capture', 'Creates a backlog task') and names the resource ('task or improvement idea into a project'). It distinguishes from sibling goal-create by calling itself a 'Lightweight alternative... when you need minimal ceremony.'

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 frames the tool as a lightweight alternative to goal-create for minimal ceremony, implying the alternative for more formal creation. It also notes the default project fallback and auto-tagging, but does not state explicit when-not conditions. The contrast with goal-create gives sufficient context.

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

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

The readOnlyHint annotation already signals this is a safe read operation. The description adds the return behavior of a nested tree with node fields, but does not disclose any limitations, permissions, or other behavioral aspects. It is consistent with the annotation but provides only modest extra context.

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

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

The description is two concise sentences, immediately front-loading the action and scope. It avoids filler and provides the essential field list in a compact structure.

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

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

Given the simple read-only nature with two optional parameters and no output schema, the description sufficiently covers the operation and expected response shape by including the node fields and nested children array. It is complete for a tool of this complexity.

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

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

The input schema already documents both parameters (projectId and rootId) with Russian descriptions, and the description repeats the same semantics in English, adding clarity for non-Russian users but no new technical information. The 'optional' nature is also conveyed in the schema. Thus it meets the baseline without significantly augmenting schema coverage.

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

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

The description uses 'Fetch' as a specific verb and clearly identifies the resource as 'the full goal hierarchy as a nested tree'. This differentiates it from sibling tools like goal-get and goal-list, which likely return flat or individual data, and the mention of 'nested tree' makes the scope explicit.

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

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

The description explains the tool's primary use case (fetching the full hierarchy) and describes the optional filters for scoping by project or subtree, which clarifies when to use it. However, it does not explicitly contrast it with alternative tools such as goal-list or goal-get, so no explicit when-not-to-use guidance is provided.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses partial-update semantics, valid status transitions, Grove mode enforcement rules (in_progress requires AC, done requires evidence), and the return value. This is rich behavioral context that helps the agent understand side effects and constraints.

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

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

The description is three sentences long, front-loaded with the most important information (partial update semantics) and then providing necessary details about validation and mode gates. Every sentence delivers value 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 tool with 10 parameters and non-trivial validation logic, the description covers all essential aspects: partial semantics, updatable fields, validation rules, mode-specific gates, and return value. No output schema is present, but the return description is adequate. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the heavy lifting is done by the schema. The tool description lists the updatable fields (title, status, priority, etc.) but does not add per-parameter details beyond what the schema already provides. The status transition and gate rules add some context for status/priority, but not enough to exceed the baseline of 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 a specific verb+resource: 'Partial update of a goal', and explains the core semantics (only fields passed are changed). This clearly distinguishes it from sibling tools like goal-create, goal-delete, and goal-move, which perform different 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 indicates when to use this tool by listing updatable fields and the supported behavior (status transitions, Grove mode gates). It does not explicitly name alternative tools, but the distinct role of 'partial update' is implied. The lack of explicit exclusions (e.g., 'for adding criteria use goal-add-criterion') prevents a 5.

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

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

Annotations already indicate a mutable (readOnlyHint=false) and idempotent (idempotentHint=true) operation. The description adds the key behavioral constraint that status is not manually changeable, and clarifies that transitions occur via evidence judge verdicts. This goes beyond the annotations and discloses a non-obvious 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?

Two sentences, front-loaded with the main purpose. The first sentence states exactly what the tool does, and the second adds a critical limitation without redundancy. No filler or repetition of schema 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?

The tool is simple (3 params, no output schema). The description covers the core update behavior and the key status limitation. Though it doesn't mention that text and signpost are optional (only assumptionId required), the schema already conveys that. Overall, it's sufficiently complete for an agent to use correctly.

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

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

The input schema provides 100% coverage with descriptions for each parameter (e.g., 'New text of assumption', 'New failure indicator', 'UUID of assumption'). The description adds no additional parameter-level nuance, so the baseline 3 applies.

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

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

The description states a specific verb 'Update' and resource 'assumption' with the exact fields 'text or signpost'. This clearly distinguishes it from sibling tools like goal-update (for goals) and goal-update-criterion (for criteria). The additional status constraint clarifies the scope further.

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 provides clear context: this tool is for updating assumption text/signpost, not for status changes. The description explicitly states 'Status cannot be changed manually' and points to evidence judge verdicts as the alternative mechanism, though it doesn't name a specific alternative tool. This gives a clear when-not and some alternative guidance.

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

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

The description discloses state-dependent permissions (backlog vs. done) and behavioral effects of the quality linter (blocking vs. advisory). It also mentions return details. This adds significant context beyond the readOnlyHint and idempotentHint annotations, with no contradiction.

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

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

Three sentences: the first states the core purpose, the second and third pack mode-specific constraints. No fluff, front-loaded, and every sentence earns its place.

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

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

Given no output schema, the description helpfully notes that it returns updated criterion details and quality findings. It also covers mode restrictions and linter behavior. Missing minor edge-case info, but sufficient for a simple 2-parameter update tool.

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

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

Schema coverage is 100% with helpful descriptions for both text and criterionId. The description only clarifies that the tool updates text, adding minimal extra meaning. Meets the baseline for fully documented schemas.

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 ('Update the text') with a clear resource ('an acceptance criterion'), which distinguishes it from sibling tools like goal-add-criterion or goal-remove-criterion. The verb is precise and the scope is explicit.

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

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

It explicitly explains when to use the tool in each mode: backup-only in Grove mode and until goal done in Standard mode. While it does not name alternative tools, it conveys clear conditional usage constraints, which is strong 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 (readOnlyHint=false, idempotentHint=true), the description adds concrete behavioral details: idempotent returns already_existed=true, self-references are rejected, and no cycle detection. This gives the agent a solid understanding of side effects and limitations.

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

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

Three sentences, front-loaded with the primary purpose, then key behaviors. Every sentence is informative with no padding. Excellent conciseness and structure.

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

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

For a simple tool with complete schema and necessary behavioral caveats (idempotency, self-reference, cycles), the description is nearly complete. It could mention return format or error cases, but no output schema exists, and the critical behavioral context is covered.

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

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

Schema coverage is 100% with descriptions for both parameters, including UUID/slug format. The description reiterates this but adds no new meaning beyond the schema. Baseline 3 applies as the schema does the heavy lifting.

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

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

The description uses a specific verb 'Declare' with a clear resource 'project dependency' and relationship type 'depends-on'. It clearly differentiates from sibling tools like project-remove-dependency by stating the action is to add/declare a dependency.

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

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

The description implies when to use it (adding a dependency) and includes important constraints (self-references rejected, no cycle detection) that guide usage. It doesn't explicitly name alternatives, but the sibling list and the action make the context 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?

Discloses rejection behavior for duplicate slugs ('duplicates are rejected with existing slugs list') and the return payload ('Returns the created project with id, slug, and webUrl'). These go beyond the minimal annotations (readOnlyHint=false, idempotentHint=false) and help 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?

Three sentences: action, requirements/options, and returns/error handling. No redundancy; front-loaded with the core purpose.

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

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

Covers action, required/optional inputs, return values, and a specific error case. No output schema exists, so the return description is essential and provided. Minor omissions like behavior of isDefault are not addressed, but overall adequate.

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% (all 9 params have descriptions). The description consolidates optional params and adds the global uniqueness requirement for slug, but does not significantly add beyond the schema, so baseline 3 applies.

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

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

The description opens with 'Create a new project container for goals,' using a specific verb and resource. It distinguishes from sibling project tools like project-get/update/delete by focusing on creation. Clear and unambiguous.

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

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

It states that 'Requires title and a unique slug' and provides format rules, giving prerequisites for use. It doesn't explicitly name alternatives or exclusions, but the creation context is clear. The uniqueness constraint is a key usage 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds critical behavior: rejection with goals count unless force=true, and the return of deleted title, slug, and goals_deleted count, exceeding annotation context.

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

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

Three sentences, front-loaded with the main action, no redundant words. Each sentence contributes necessary information about action, condition, and return values.

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 delete tool with optional cascade, the description covers the main action, conditional behavior, rejection, and return values. With no output schema, the return info is valuable. Minor omission of behavior for non-existent project, but not critical.

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

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

Schema coverage is 100% with both parameters described. The description enhances this by explaining the conditional cascade semantics of force and the returned goals_deleted count, adding meaning 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 'Delete a project' with a specific verb and resource. It also details the force parameter behavior, distinguishing this tool from sibling tools like project-update or project-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 description gives explicit guidance on when to use force: if the project has goals, pass force=true to cascade-delete; otherwise, the call is rejected. It doesn't name alternatives, but the context is clear.

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

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

The readOnlyHint annotation already establishes safety, and the description adds valuable context by detailing the return payload (field lists, status counts, dependencies). No contradictions or undisclosed side effects exist.

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 efficiently enumerates the returned fields. It is slightly long due to the field list, but every item adds information and there is no fluff.

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

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

With no output schema, the description thoroughly discloses the return content: project metadata, status, repository info, goal status breakdown, and dependencies. This is complete for a single-project read operation.

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

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

Schema description coverage is 100% for the only parameter (projectId), so the schema fully documents it. The tool description does not add additional parameter syntax or formatting details beyond the schema, matching the baseline for high coverage.

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

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

The description uses a specific verb ('Fetch') and clearly defines the resource ('full project details') with an enumerated scope of returned fields. This distinguishes it from sibling tools like project-list (which presumably lists projects) and goal-get (for goals).

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

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

The description implies usage for retrieving comprehensive data for a single project but does not explicitly state when to use it versus alternatives such as project-list or project-update. No exclusions or alternative tool references 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?

With readOnlyHint=true in annotations, the safety profile is already conveyed. The description adds useful behavioral context by listing the exact return fields (id, title, slug, webUrl, icon, goals_count) and the optional status filter, which are not covered by the annotation.

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

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

The description is two sentences long, front-loaded with the core purpose, followed by return fields and an alternative tool mention. Every sentence 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?

The description fully covers the tool's purpose, parameter, return fields, and provides a pointer to the more detailed sibling tool. For a simple list operation with one optional parameter, this is complete enough for an agent to select and invoke correctly.

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

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

The input schema already documents the single 'status' parameter with the enum values active/archived/paused. The description repeats these values without adding new semantic detail, so with 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states 'List all projects with optional status filter', providing a specific verb and resource. It also enumerates the returned fields and explicitly distinguishes itself from the sibling tool 'project-get' by noting 'Use project-get for full details'.

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 names an alternative tool ('project-get') and the condition for using it ('for full details with goals breakdown by status'). This tells the agent when to prefer this tool over the sibling, though it does not state exhaustive exclusions.

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

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

The annotations provide readOnlyHint=false and idempotentHint=true, and the description adds return semantics (removed=true/false) and the two lookup modes. It does not discuss parameter precedence or error cases, but the disclosed behavior goes beyond the annotations.

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

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

Two sentences, front-loaded with purpose, no fluff. Every clause adds information about lookup modes or return values.

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 appropriately explains the return value. It covers both lookup modes and the not-found case. Minor ambiguity remains about what happens if conflicting parameters are provided, but the overall tool is simple and the description 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%, so baseline is 3. The description adds value by grouping parameters into modes and clarifies that dependencyId is the UUID of the link, while projectId + dependsOnProjectId use UUIDs or slugs. This enriches the schema descriptions.

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

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

The description clearly states 'Remove a project dependency' with a specific verb and resource. It distinguishes itself from siblings like project-add-dependency and project-delete by specifying it targets the dependency link itself.

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 explains the two lookup modes (by dependencyId or by projectId + dependsOnProjectId), offering concrete usage context. It doesn't explicitly exclude alternatives, but the operation is distinct enough from sibling tools that no exclusions are 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?

Annotations disclose idempotentHint=true and readOnlyHint=false, but the description adds crucial behavioral details: it is a partial update (not a full replacement), all updatable fields are enumerated with allowed values, and it returns the updated project with all fields. No contradiction with annotations; the extra transparency significantly aids an agent in invoking the tool safely and correctly.

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

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

The description is concise relative to its complexity: two sentences pack the key behavior, a complete list of updatable fields with allowed values, and the return type. The second sentence is long but logically grouped, and front-loads the most critical behavioral caveat (partial update). It could be slightly more structured, but it remains efficient and readable.

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 17 parameters, no output schema, and partial update semantics, the description covers all necessary aspects: it lists every updatable field, specifies allowed values for enumerated fields, clarifies that omitted fields are untouched, and states that the response is the full updated project. It does not mention error cases or prerequisites like project existence, but the required projectId is in the schema. Overall, it is sufficiently complete for a complex mutation tool.

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

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

Schema descriptions already cover 100% of parameters and include allowed values (e.g., status: active, archived, paused). The description's list of fields and values largely duplicates this information, adding minimal new meaning for individual parameters. It does not explain the semantics of ambiguous fields like repositoryPath or repositoryUrl 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 clearly states the tool performs a partial update of a project, explicitly listing the updatable fields and emphasizing that only passed fields change. This distinguishes it from siblings like project-create, project-delete, project-get, and project-list.

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 explains the partial update semantics: only fields you pass are changed, omitted fields are untouched. This provides clear guidance on when to use the tool (to modify one or more specific project fields without affecting others) and implicitly differentiates it from full replacement or other project operations.

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