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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false and idempotentHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: entries are immutable (no call edits or deletes; correction happens via a new entry referencing the old one in refs) and an empty title is refused with the entry_fields_invalid error listing the offending fields. It still omits auth requirements and rate limits, so not a full 5.

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

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

Roughly 90 words, front-loaded with the core action and its type set, then immutability, then sibling routing. Sentences earn their place, though the opening "without payload" phrasing is slightly odd given the tool does accept a body and may momentarily confuse an agent.

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 multi-type creation tool with a full output schema and complete annotations, the description covers purpose, type selection, immutability semantics, sibling routing and a refusal example. It leaves out any mention of the key or idempotency_key parameters, which the schema carries, so it is strong but not exhaustive.

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

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

Schema description coverage is 100%, so the schema already documents key, body, refs, type and idempotency_key with examples and error contracts; baseline is 3. The description's first sentence partly restates the type enum, and its only additional parameter information is the refusal-on-empty-title error path, which adds marginal value over 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?

States a specific verb and resource ("Files an entry") and enumerates the exact entry types the tool accepts, so an agent knows precisely what it creates. It also names the sibling tools that handle the excluded entry kinds (add_summary, ask, answer, add_verdict, resolve), making it distinguishable without opening schemas.

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

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

Gives explicit when-to-use guidance via the type enumeration in the description and the detailed per-type semantics carried in the schema's enum. It also routes the agent to named alternatives for summaries, questions, answers, verdicts and resolutions, and clarifies edge cases (e.g. an observation about one's own task is a finding, not a remark).

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 non-read-only, non-destructive, non-idempotent, closed-world. The description goes beyond them by disclosing that entries stay as filed, that decisions remain in force until superseded, that status is computed on read, and that an idempotency key changes retry behavior. It does not discuss permissions or rate limits, so it stops short of the top mark.

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?

Purpose is front-loaded in the first sentence, and each subsequent paragraph covers a distinct concern (numbering/addressing, decision lifecycle, error behavior). The decision-lifecycle paragraph is slightly dense and could be tightened, but no sentence is filler.

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

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

With an output schema present, return values need not be explained, and the description covers mutation semantics, idempotency, and failure modes (`entry_fields_invalid`, `project_not_found`, `decision_not_in_force`). It is nearly complete for a 7-parameter write tool, missing only permission/auth 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%, so the baseline is 3. The description nonetheless adds real meaning: entry numbering counts inside the project, `TRK#7` addresses a project entry from `refs`, and `supersedes` must name in-force decisions of the same project. This exceeds what the schema descriptions alone convey.

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

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

States a specific verb (files) and resource (an entry in a project's case) and enumerates the entry types it accepts. It explicitly contrasts with the sibling `add_entry` by scoping itself to entries that concern the project rather than one of its tasks, so an agent can disambiguate without opening either schema.

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

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

The description draws the project-vs-task boundary clearly ('concerns the project rather than one of its tasks') and repeatedly frames behavior relative to `add_entry`, which routes selection well. It stops short of an explicit 'use X when…, use Y when…' directive, so it is clear context rather than full routing guidance.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds real behavioral detail beyond them: empty parts are refused with `entry_fields_invalid`, and the index title is derived from the first line of `done` and returned in the response. It does not cover permissions or any rate/size limits.

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

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

Front-loaded with the core statement, then definitions and routing. The middle paragraph defining 'a significant step' is somewhat discursive but earns its place by setting the bar for filing. No redundant filler sentences.

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

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

With an output schema present, return values need no explanation, and the description supplies the error codes, the four-part structure, and the close_task relationship. For a 6-param write tool this is nearly complete; only caller-side concerns like permissions or limits are absent.

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 the first-line title behavior of `done`, the `nothing` convention for blockers, and the idempotency key semantics. The description's statements about the four non-empty parts and the index title largely restate what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Files a summary: the handover note of a case, in four parts') and immediately defines what a summary contains. It also distinguishes itself from the sibling close_task, which files the final summary with `unmeasured`, so an agent can tell the two apart without opening either schema.

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

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

Gives an explicit criterion for when this tool is warranted ('A significant step is a decision made, a finished part of the work, a failure that changes the plan...') and routes the end-of-task case to close_task. It stops short of naming alternatives like add_entry or stating exclusions, so it is clear context without full when/when-not coverage.

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

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

Annotations declare the safety profile (readOnly=false, destructive=false, openWorld=false, idempotent=false), but the description adds real behavior: the latest verdict on a check replaces earlier ones, earlier-pass verdicts persist without counting, and replacement happens for both passed and failed outcomes. Auth requirements and error/return behavior are left to the schema.

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

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

Purpose is front-loaded in the first sentence, with pass/replacement rules following. It is dense and the sentence about failed/passed filing is slightly convoluted, but no sentence is pure 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?

A mutation tool with a full output schema, so return values need not be explained, and annotations cover safety. The pass semantics and replacement behavior that an agent needs to avoid mis-filing verdicts are present; permission/token requirements are the main omission.

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

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

Schema description coverage is 100%, so the schema already documents key, outcome, check_no, evidence, and idempotency_key in depth. The description adds no parameter-level meaning beyond that, 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?

States a specific verb and resource: 'Files the outcome of one review check', scoped to the task's current pass and its assignee. It also explicitly names the nearest overlapping sibling ('`close_task` also takes verdicts, together with the closing'), so an agent can separate filing a verdict from closing a task.

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 establishes when a verdict counts (current pass only, latest replaces earlier) and implies the division of labor with close_task. It stops short of an explicit 'use this tool when / not when' rule and gives no prerequisites for calling it.

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

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

Despite annotations covering safety (readOnly=false, destructive=false), the description adds substantial non-obvious behavior: the first answer closes the question while later ones append, neither a question nor an answer changes task status, and withdrawn/replaced drop out of `questions` in `get_task` and the open-question counts but stay in the case. It also discloses the title-construction rule. That is real context the annotations do not provide.

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

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

Three short paragraphs, front-loaded with the core purpose and outcome list before the state-effect details. Dense but every sentence carries information; only the feathered wording around 'stays in the case with this entry' costs a little clarity.

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

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

With an output schema present and 100% schema coverage, the description does not need to restate returns; it correctly focuses on actor permissions and state transitions for a 6-parameter mutation tool. It is essentially complete, with only the sibling-routing guidance missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including outcome semantics, idempotency binding, and the refusal reasons. The description adds only marginal meaning beyond the schema (the tracker building the title from reference and outcome), 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 first sentence gives a specific verb (answers/closes) and resource (a question of the same task) plus the alternate outcomes, so an agent can immediately tell it apart from the paired `ask` and from generic entry-adders like `add_entry` or `add_verdict`. The counterpart semantics (this is the answering side of `ask`) are 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 who may call it ('any holder of a `task` token answers, in any task') and when the withdrawn/replaced outcomes are legal, which is useful context. But it never positions the tool against near neighbors (add_entry, resolve, add_verdict) or says when to answer versus add a plain entry, so usage is only implied.

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

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

Adds a great deal beyond the annotations: the freeze semantics, the exact refusal code `project_archived`, the single exception (`unlink` of a task-linked link), and the fact that reads still work. This also clarifies the non-idempotent annotation by stating a repeated archive is refused rather than a no-op.

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

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

Front-loads the action and consequence, then details the frozen state and the exception. Three paragraphs is slightly long and repeats `project_archived`, but nearly every sentence carries distinct behavioral information.

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

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

An output schema exists so return values need not be explained, and the description covers preconditions, postconditions, error behavior, and the one surviving mutation. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both `key` and `reason` are already documented with their error codes in the schema. The description adds only the routing context around `reason` being filed in the archived entry, which the schema also states. 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?

States a specific verb and resource ('Archives a project') plus the side effect ('files an `archived` entry in its case'). The closing reference to `restore_project` and the refusal codes make it clearly distinguishable from sibling mutation tools.

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

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

Gives strong contextual guidance: what gets frozen, what is refused afterward, and that `restore_project` is the inverse operation. It does not explicitly name when to prefer this over other project-mutating siblings, but the preconditions (project must not already be archived) are clear.

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

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

Annotations already cover the mutating/non-idempotent/non-destructive profile, so the bar is lower. The description adds meaningful behavioral traits beyond annotations: the tracker delivers nothing (unusual semantics), open-question counting, the effect of blocking on in_progress entry, and the status behavior when the last blocking question is answered.

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?

It is front-loaded with the core action, but the body is unfocused and redundant: the delivery/waits/waiting behavior is explained in multiple sentences with some circular phrasing (e.g. 'carrier of a wait on its addressee'), and information spills into prose that could be tighter.

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 tool's unusual lifecycle semantics (open until answered, blocking semantics, effect of the last answer) and hints at reading records via get_task/read_entries. With a 6-param schema and output schema present, this is fairly complete, though the usage boundary against 'answer' and 'resolve' could be clearer.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters in detail. The description doesn't add parameter-level semantics beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: it files a question to registry participants and explains that the tracker delivers nothing, distinguishing it from a notify/message tool. It doesn't explicitly contrast with the sibling 'answer' tool, but the resource and action are 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?

Usage is implied but not framed with explicit when/when-not guidance or named alternatives. The final sentence implies that reading existing records uses get_task/read_entries rather than a question, but it's not framed as a routing rule for the agent.

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

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

Annotations declare non-destructive and non-read-only, but the description adds crucial behavioral context: atomicity ('in one transaction'), refusal semantics ('files nothing and leaves the status as it was'), the exact exit conditions and their error codes (`checks_not_passed`, `task_has_unclosed_children`, `transition_not_allowed`, `entry_fields_invalid`), warning side effects (`open_warnings` at 1 until acceptance/remark), and the `blocks` side effect. This is far beyond what annotations provide.

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

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

The description is well-structured: a lead sentence establishing purpose, then paragraphs on refusal, exit conditions, warnings, parent summaries, and downstream effects. It is dense with useful information but every sentence earns its place. Slightly long, but appropriate for the complexity of the operation.

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 richness of the schema (nested objects with descriptions) and an output schema, the description supplies all the behavioral and transactional context an agent needs: atomicity, refusal outcomes, exit conditions, warning behavior, parent/child summary semantics, and downstream `blocks` effects. Nothing material is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it specifies the filing order (entries, then verdicts, then summary), clarifies that verdicts may be empty because earlier verdicts count, and notes that the summary reports on the entries and verdicts before it. This gives the agent information not fully explicit in the schema 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 states the specific verb and resource (closes a task) and enumerates the ordered operations (files entries, verdicts, summary, moves to done) in a single transaction. It also asserts uniqueness ('It is the only way into `done`'), which distinguishes it from `transition` and `add_summary` among siblings.

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

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

It clearly establishes when to use this tool (to reach `done`) and implicitly when not (any other status transition goes through `transition`). It distinguishes its effect from `add_verdict` by noting that a `failed` verdict sent here leaves no trace if the call is refused. It does not name `transition` or `update_task` as explicit alternatives, so it stays short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the description only needs to add mutation-specific context. It adds none: nothing about the project appearing in list_projects, key immutability, or the retry behavior that the idempotency_key parameter exists for. The single clause is essentially a restatement of the name.

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?

One short, front-loaded sentence with no filler. It is efficient, though its brevity comes partly from omitting information the tool needs.

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

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

An output schema exists, so return values need not be explained, and the input schema is unusually thorough. However, for a creation tool with zero annotation detail beyond safety flags, the description leaves the agent without any statement of side effects or post-creation state.

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

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

Schema description coverage is 100%, so the schema already documents key format, the 320-character description limit, and idempotency semantics in detail. The description names key/title/description but omits idempotency_key and adds no format detail beyond the schema, 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?

States a specific verb (creates) and resource (project) with the main fields it accepts, which separates it cleanly from create_task and update_project. It stops short of noting scope or how the new project relates to siblings like list_projects, but the core purpose is 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?

There is no guidance on when to create a project versus using update_project or archive_project, and no prerequisites or alternatives are mentioned. The agent must infer usage from the name alone.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, which correctly frame a write), the description discloses lifecycle behavior: tasks start only in backlog, parent linking writes link_added on both tasks and returns parent_entry, and empty title/description is refused with task_fields_invalid. It doesn't disclose idempotency_key semantics (that lives in the schema), but the added behavioral context is substantial.

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

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

Front-loads the core behavior (creation only into backlog) and then covers parent linkage, split criteria, and validation errors in a logical order. The middle paragraph on when a child takes part of the parent's work is somewhat tangential and jargon-heavy for a creation tool, costing a little tightness.

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

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

An output schema exists, so return values needn't be re-explained, yet the description still notes the tracker-issued key. Combined with lifecycle, linkage, and error coverage it is nearly complete for a 9-parameter mutation; only the idempotency_key retry contract is left entirely to the schema.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above that by explaining parent-link side effects (link_added on both tasks, parent_entry in the response) that the schema only sketches. It does not add meaning for assignee, priority, sections, or decisions beyond what the schema already states.

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

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

Opens with a specific verb and resource ('Creates a task in `backlog`') and immediately pins the initial status, so the agent can distinguish it from update_task, close_task, or transition. The parent/child and validation details all reinforce a single unambiguous purpose.

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

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

Gives real routing guidance: it explains when work should become a child task (parent output splits, checks can't pass in one pass, dependency missing) and names update_task as the follow-up for completing sections. It stops short of an explicit 'when not to use this vs. create_project', so it is strong context without full 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, idempotentHint, and openWorldHint=false, covering the safety profile. The description adds the contents of the returned document, but the unknown-key refusal is already stated in the parameter schema, and a dedicated output schema exists, so little is added beyond structured fields.

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

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

Two short sentences with the action front-loaded; the enumeration of return fields is dense but scannable. The second sentence about `list_projects` earns its place as a key-sourcing hint, though the phrasing 'index of the project's case' is slightly opaque.

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 read tool with full schema coverage and an output schema, the definition is essentially complete; the return-field enumeration is mildly redundant given the output schema, but nothing an agent needs to call it is missing.

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

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

Schema description coverage is 100% and the single `key` parameter is fully documented in-schema, including case-insensitivity, example, and the `project_not_found` error. The description adds no syntax or format detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Returns one project by its key') and enumerates the payload, which immediately distinguishes it from the sibling 'list_projects'. An agent can tell single-fetch from bulk-list without opening either schema.

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

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

The description points to `list_projects` as the source of valid keys, giving the agent a concrete path to satisfy the required `key`. It does not spell out when-not to use this tool or name other alternatives (e.g. search_tasks), but the single-vs-list distinction is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), and the description adds substantial behavioral context beyond them: remarks do not block in_progress or change status and stay until resolve gives an outcome, and transitions lists table targets rather than pre-validated moves. This is exactly the kind of non-obvious behavior an agent needs.

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

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

Long and dense for a read tool, but front-loaded with the purpose and organized by return field, with each paragraph carrying semantic content rather than restating the output schema. The field-by-field enumeration is heavier than strictly necessary but still earns its place.

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

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

An output schema exists so return values need not be re-explained, yet the description supplies the semantics the schema cannot express — how parent/children differ from links, how summary `no` bounds coverage, and what a remark does and does not do. Complete for an agent deciding whether and how to call this tool.

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

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

Schema description coverage is 100% and the single `key` parameter is fully documented in the schema itself, including the task_not_found refusal and case-insensitivity. The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource — returns everything about one task in a single call — and immediately enumerates the payload (card, parent/children, links, decisions, summary, questions, remarks, index, transitions). An agent can distinguish this from search_tasks or read_entries without opening a schema.

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

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

No explicit 'when to use' sentence, but it routes the agent within the family: entry bodies come from read_entries, entries beyond the summary come from read_entries with after_no, and actual transition validation belongs to the transition call. That is clear context, though it never states when to prefer get_task over search_tasks for a single known key.

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 carry the safe/unsafe profile; the description supplies the substantive behavior: duplicate links refused with `link_exists`, cycles with `link_cycle_detected`, self-links with `link_self_not_allowed`, closed-task refusals, and the side effect of raising a task's `blocked` feature and keeping it out of `in_progress`. This is rich, non-redundant disclosure.

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 lead sentence is front-loaded with the action and effect, and the following paragraphs are organized by topic (kind roles, hierarchy, blocking, closed tasks). It is dense with error codes but each clause carries distinct information, so little is wasted.

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 link-mutation tool with an output schema already covering return shape, the description covers the edge cases an agent needs: valid kinds, one-parent constraint, cycle/self/closed-task refusals, and side effects on cards and the `blocked` feature. Nothing material is missing.

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

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

Schema coverage is 100% and the `kind` enum is already well documented in the schema, so baseline is 3. The description adds meaning beyond the schema by explaining that `parent`/`child` set hierarchy shown via `get_task` fields rather than `links`, and how the same link renders from the opposite side.

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

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

States a concrete verb and resource ('Links two tasks') plus the side effect ('files `link_added` in both cases'). It also clearly separates this from the sibling `unlink` and from hierarchy operations, so the agent knows exactly what this tool does.

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

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

Explains the semantics of each `kind` value, the one-parent rule, cycle refusal, and what closed tasks accept, which effectively tells the agent when a link is valid or refused. It never names a competing tool or an explicit 'use X instead' escape hatch (e.g. vs `unlink` or `update_task`), so it stops short of top-tier routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the registry contains humans and permanent agents only, and temporary agents are deliberately excluded, which is non-obvious and affects result interpretation.

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

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

Two tight sentences, front-loaded with what is listed, then the scope qualifier. No filler, no repetition of the title.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. The description is complete for a read-only paginated list; only explicit pagination guidance (e.g., how limit/cursor interact) would add much, and that lives in the schema.

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

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

Schema coverage is 100% and both limit and cursor are already documented in the schema, so the description adds nothing about pagination semantics. Baseline 3 is appropriate when 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?

States a specific verb (Lists) and resource (participant registry), and defines the resource's scope: humans and permanent agents, the possible addressees of a question. It also carves out what the registry is not (temporary agents are absent), which lets an agent distinguish it from the register_participant/update_participant siblings.

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

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

Usage is implied by the semantic framing ('the possible addressees of a question'), which tells the agent when the list is relevant, but there is no explicit when-to-use/when-not or reference to alternatives such as register_participant. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful behavior beyond that: results come back paginated 'one page at a time', and it clarifies that archived projects are excluded unless requested while remaining readable by key via get_project.

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

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

Two short sentences with zero filler. The paginated-listing purpose is front-loaded, and the routing note to get_project follows immediately.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile. The description still supplies pagination behavior and the archived-project nuance, leaving nothing an agent needs to call this 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 limit, cursor, and include_archived are already fully documented in the schema. The description adds no syntax or default details beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Lists the installation's projects'), names the exact fields returned (key, title, archive time), and explicitly routes to the sibling `get_project` for descriptions. An agent can distinguish this from get_project and create_project without opening a schema.

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

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

It gives clear context for the tool's role and names `get_project` as the alternative when a description is needed. It does not state when NOT to use it (e.g. versus search_tasks or a filtered listing), but the enumeration use case is unambiguous.

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

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

Annotations only give the generic mutation profile (readOnly=false, destructive=false, idempotent=false). The description goes far beyond by disclosing key-reassignment mechanics (`previous_keys`, one key per project), that status/sections/links/children stay intact, closed tasks move, frozen projects fail, and that a batch refusal of one task leaves others moved.

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?

Dense but well-front-loaded: the core action and key mechanics lead, with error/batch semantics after. Four paragraphs is long for a 3-parameter tool, but nearly every sentence carries distinct behavioral information rather than filler.

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

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

An output schema exists, so return values need not be explained, yet the description still enumerates `results` states (`moved`/`already`/`error`) and failure codes. Combined with the mutation semantics and batch rules, an agent has everything needed to call and interpret 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 coverage is 100%, so the 3 baseline is already met by the schema. The description adds integration meaning: that `reason` is filed in the `moved` entry of the case, that a key list follows list order, and that prior keys continue to address the task — context not present in the schema text itself.

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

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

States a specific verb and resource ('Moves a task to another project') and immediately enriches it with scoping rules that no sibling like update_task or create_task shares. An agent can distinguish this from every sibling on the strength of the first clause alone.

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?

Rich operational context: when a move fails (`project_archived`), how batches behave, and what refusals are pre-validated. It does not, however, explicitly name an alternative tool or state when to prefer this over update_task, so it stops short of the 5-tier routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so safety is covered. The description adds genuine domain context beyond them: `decision` and `attempt` entries record choices already made and attempts already tried, including failed ones. It does not discuss paging or result shape, but an output schema exists.

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

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

Front-loaded with the core behavior and scoping, then a tightly written sentence on filter combination, then a one-line pointer to the sibling. The two filter examples are slightly more elaborate than strictly needed, but nothing is padded.

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 6 params, full schema coverage, an output schema, and safety annotations, the description only needs to carry filtering and routing semantics, which it does. It is complete enough to call correctly and only marginally omits anything an agent would want.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: how `types` and `after_no` compose ('both together the entries of those types filed after it'), with a concrete example. That is value beyond the field-level descriptions.

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

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

The description states a specific verb and resource ('Returns entry bodies of one task's case, with payload, in number order'), which distinguishes it from search_tasks and roughly from read_project_entries via the 'one task's case' scoping. It stops short of explicitly naming the read_project_entries sibling it is most easily confused with.

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 routes the agent to `wait_journal` for the opposite need (streaming many cases plus waiting for new entries), and spells out how filters combine with `and`. There is no explicit 'when not to use this' beyond that routing hint, 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?

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds real behavioral context: results are ordered by entry number, payloads are included, filters AND together, and `attribute` narrows to created/changed/removed entries. Pagination mechanics are left to the schema.

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

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

Front-loaded with the core behavior in the first sentence, followed by scoping and filter semantics. Every sentence carries information, though the middle sentence is dense and packs several distinct facts into one block.

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

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

An output schema exists, so return values need not be described, and the description covers what the case holds versus tracker entries, ordering, filtering and the index alternative. Minor gaps remain around pagination interplay and default page size, but the essential call-shaping information is present.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by explaining that filters combine with `and` and that `attribute` returns the attribute's creation/change/removal history. It does not clarify how `nos`, `after_no`, `cursor` and `limit` interact, so it is above baseline but not exhaustive.

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

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

States a specific verb and resource ('Returns the bodies of a project's case entries, payload included, ordered by entry number') and immediately scopes it against siblings: the case index with titles only comes with `get_project`, and filter semantics mirror `read_entries`. An agent can distinguish this from `get_project` and `read_entries` without opening any schema.

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

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

Gives clear routing context ('The case index, titles only, comes with `get_project`') and explains that filters combine with `and`, plus the special semantics of `attribute`. It does not explicitly state when to prefer this over `read_entries` beyond the filter-semantics reference, so it stops short of full when/when-not guidance.

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

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

Annotations already declare write semantics (readOnlyHint=false), non-destructive, closed-world, and non-idempotent, so the description only needs to add what they cannot convey. It usefully discloses that the new participant's token is issued through the REST API (i.e. not returned here), but says nothing about authorization needs, side effects on existing data, or error surface.

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

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

Two short sentences, zero padding: the core action comes first and the alternative-tool routing follows. Nothing is repeated from the title or restated from the schema.

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

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

With an output schema present the return values need not be explained, and annotations plus the rich schema cover safety and argument semantics. The token-issuance detail closes the main behavioral gap, leaving only minor omissions such as permissions or conflict-handling expectations.

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 name format, immutability, error codes, idempotency-key semantics and the description field are all fully documented in the schema itself. The description adds no parameter-level meaning beyond that, which is the baseline expectation here.

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

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

States a specific verb and resource ('Registers a human or a permanent agent') and explicitly separates this tool from the sibling update_participant, which changes an existing participant's description. The only softness is the unexplained term 'permanent agent', which leaves the human/agent distinction slightly fuzzy beyond the schema enum.

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 second sentence routes the agent away from this tool when the participant already exists ('An existing participant's description is changed by update_participant'), which is a concrete when-not-this condition naming the alternative. It does not, however, state prerequisites or what happens if you call it for something already registered beyond what the schema says.

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

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

Adds real context beyond the annotations: the removal is not silent (it files a case entry), history is retained, and the operation is effectively recoverable via a later set_attribute — which coherently explains why destructiveHint=false despite a delete-like verb. The trailing 'A `task` token removes attributes' hints at an auth requirement but is too terse to be fully actionable.

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

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

Three short paragraphs, front-loaded with the action and side effect, then error behavior. The final sentence about a `task` token is cryptic and slightly detracts from an otherwise tight 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?

An output schema exists, so return values need not be described, and the description covers side effects, error codes, history retention and idempotency context. Only the authorization/`task` token statement is underspecified.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds behavior not present in the schema: the refusal code for an unknown attribute name and the fact that the last value is persisted alongside the reason.

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

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

States a specific verb and resource ('Removes a project attribute') plus the side effect (files an `attribute_removed` entry in the case with the last value and reason). This clearly distinguishes it from the sibling `set_attribute`, which is even named in the text.

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

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

Gives the failure condition for a non-matching name (`attribute_not_found`) and tells the agent that re-adding requires a separate `set_attribute` call, so the lifecycle is clear. It stops short of an explicit 'use this when X, use set_attribute when Y' routing statement.

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

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

Annotations only declare the safety profile (not read-only, not destructive, not idempotent), so the description adds real value by disclosing that every outcome removes the remark from `open_remarks` while `accepted` parks it in `remarks_in_work` until the continuation task closes, plus how the resulting title is composed. It does not cover permissions or preconditions (e.g. remark must be open), leaving some behavioral gaps.

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

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

Three tight sentences with the core action front-loaded and the state-transition nuance following. No filler, though the second sentence is dense enough to require careful reading.

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

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

With an output schema present and full parameter documentation, the description only needs to convey non-obvious behavior, and it does so for state transitions and title construction. Missing preconditions/permission context keeps it short of complete.

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

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

Schema coverage is 100%, so all six parameters, including the outcome enum and idempotency_key, are already documented in the schema; baseline is 3. The description adds only the derived-title detail and per-outcome state effects, not new parameter syntax.

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

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

States a specific verb and resource ("Resolves a remark on a task") and further scopes it with "its outcome and where the work went." An agent can tell this apart from generic entry-writing siblings like add_entry or add_verdict, though no sibling is named explicitly.

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

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

The description explains the effect of each outcome and the state it moves the remark into, which implicitly guides selection of the right outcome, but it never says when to use this tool versus ask/answer/add_verdict. Usage is implied rather than 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 declare this is a non-read-only, non-destructive, non-idempotent mutation; the description adds substantive behavior beyond that — it writes a `restored` journal entry carrying the reason and resumes task state where archiving left off, plus the refusal code for non-archived projects. It does not discuss idempotency or permissions, but the state-transition detail is well above the annotation baseline.

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

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

Two short sentences, front-loaded with the core action and followed by the effect and the refusal condition. No filler; every clause carries information.

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

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

With an output schema present, return-value explanation is unnecessary, and the description covers the state transition and the error case. Only minor gaps remain — no explicit mention of the `archive_project` alternative or permission requirements.

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

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

Schema description coverage is 100%, so both `key` and `reason` are fully documented in the schema itself, including the refusal codes. The description's mention of the reason being 'carried in its case' duplicates the schema's statement that it is filed in the `restored` entry, adding little beyond it. 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?

States a specific verb and resource ('Brings an archived project back') and describes the concrete effects: filing a `restored` entry and resuming tasks. It doesn't explicitly name `archive_project` as the counterpart, but the archived-project framing makes the inverse relationship inferable.

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

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

Gives a clear precondition and the failure mode for violating it ('A project that is not archived is refused with `project_not_archived`'), which effectively tells the agent when not to call it. It stops short of explicitly routing to the sibling `archive_project` for the opposite operation.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavior beyond them: archived-project visibility rules, default ordering by key when sort is omitted, truncation of long text with `<field>_truncated`/`<field>_length` markers, and the exact error taxonomy with codes. This is real operational context an agent needs.

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

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

Front-loaded with the core purpose, then layered detail; every paragraph carries information. Some query examples and operator lists are restated from the query parameter description, and the mid-sentence line breaks make it slightly harder to scan, but there is little pure filler.

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

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

For a 20-parameter tool with an output schema and full annotations, the description covers the tricky cross-cutting concerns: condition combination, archived scope, ordering defaults, truncation, and error codes. Pagination via cursor is implied by the schema field, and return shape is left to the output schema, so it is complete enough without reaching 5.

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

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

Schema coverage is 100%, so the baseline is 3, but the description contributes cross-parameter semantics the schema does not: query and separate conditions combine with `and` and behave as one equivalent string. The query-language operator placement note (operator after the colon, unlike SQL) also reinforces schema content at the call level.

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

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

The opening sentence names a specific verb (Searches) and resource (tasks) and enumerates the three input modes (query string, separate conditions, or both). It also distinguishes itself from the sibling get_task by noting that a single task in full, with case and links, comes from get_task. An agent can route correctly without opening any schema.

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

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

It explains the semantics that drive selection: combined query+condition inputs are ANDed, and no condition at all selects every task of non-archived projects. The archived-project rule and the get_task pointer give contextual routing. It stops short of stating explicit when-not-to-use cases or naming other siblings (e.g. list_projects) as alternatives, so it is clear but not exhaustive.

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

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false): it discloses case-insensitive matching, that the original spelling is retained and never renamed, that values are stored as plain text with no typing or search semantics, and that the reason becomes required only on a value change. The idempotency and error-code behavior is spelled out in the schema, but the semantic consequences are explained here.

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

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

Front-loaded with the core operation, then three tight bullets for the branch conditions and one for naming persistence. The trailing fragment 'A `task` token sets attributes.' is terse to the point of ambiguity about authorization context, which slightly blunts an otherwise efficient 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?

With an output schema present and 100% parameter coverage, the description need not describe return values; it instead supplies the mutation semantics, the no-op case, and the reason-required rule. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it explains the conditional requirement of `reason` in terms of attribute state, and the naming/case behavior that governs `name`. It does not add syntax detail for `idempotency_key` or `key` 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?

States a specific verb and resource ('Sets the value of a project attribute') and immediately qualifies what an attribute is. It is distinguishable from the sibling remove_attribute and from add_project_entry, and it clarifies that one call both creates and changes.

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 three bulleted branches give precise conditions for when a call creates, changes, or no-ops, which is the core usage decision for this tool. It stops short of naming alternatives (e.g. remove_attribute or add_project_entry) or stating when an agent should prefer a different tool, so it falls just below the top band.

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 cover the safety profile (not read-only, not idempotent, not destructive, closed-world); the description goes far beyond them, disclosing named refusal codes with detail payloads, the side effect that `cancelled` clears the `blocked` feature of blocked tasks with no case entry, and the re-entry/pass semantics of `in_progress`.

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

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

The core action is front-loaded in one sentence, and the remaining prose is dense but load-bearing (refusal codes, side effects, open-task semantics). The refusal enumeration is long, but each entry carries distinct information an agent needs.

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

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

For a state-machine transition with a fixed table, the description covers preconditions, refusal reasons, side effects, and edge-case semantics (tasks waiting in `open`), and an output schema already covers the return shape. Nothing material is missing.

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

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

Schema description coverage is 100%, so `key`, `to`, and `reason` are already fully documented in the schema, including the `reason`-required cases. The description adds no parameter-level detail beyond that, 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?

States a specific verb and resource plus the mechanism ('moves a task to another status along the fixed transition table'), and explicitly routes the `done` case to the sibling `close_task`. It does not, however, differentiate itself from `move_task`, which an agent could easily confuse with a status change.

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

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

The refusal catalogue effectively defines when the tool will and will not succeed, and `close_task` is named as the correct alternative for closing. What's missing is a positive statement of when to reach for `transition` versus `update_task` or `move_task`.

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

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

Annotations only declare the safety profile (readOnly=false, idempotent=false, destructive=false, openWorld=false); the description goes well beyond that, disclosing the emitted `link_removed`/`task_closed` events, the fact that removal is symmetric across side and kind alias, and the important edge case that `parent`/`blocks` are refused on closed tasks while `relates` is removed. These are exactly the mutation semantics an agent cannot infer from 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?

Front-loads the action in the first sentence, then layers exception behavior; backticked identifiers make it scannable and every sentence carries information. The phrase 'in both cases' is slightly opaque and requires the following sentence to resolve.

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

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

With an output schema present, return values need not be described, and the description covers success, the alias/symmetry model, closed-task exceptions, and the `link_not_found` failure mode. It stops short of mentioning permissions or whether the removal is reversible, but is otherwise complete for a 3-parameter mutation.

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

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

Schema coverage is 100% and the kind enum plus `blocks`/`blocked_by` example are already documented in the schema, so the description's explanation of the `kind` alias is largely a restatement. It reinforces rather than extends parameter meaning, making the baseline 3 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?

States a specific verb (removes) plus resource (a link) and immediately names the audit event filed (`link_removed`), so the action and its side effect are unambiguous. It is clearly the inverse of the sibling `link` tool, so an agent can route between them without opening either schema.

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

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

Usage is only implied by the name; there is no explicit statement of when to unlink vs. when to use `link`, nor any prerequisite or exclusion to guide selection. It does supply operational context (symmetric removal, closed-task handling, link_not_found refusal) that helps an agent call it correctly, but this is behavior rather than use-case guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety bar is partly met. The description adds real value by specifying the exact destruction semantics — the prior description is overwritten and not retained — and by clarifying that name is immutable because it 'signs entries already filed'. That explains the destructive/idempotent profile in domain terms.

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

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

Three short, front-loaded sentences with no filler; the primary action comes first, then the immutability constraint, then the overwrite caveat. Every sentence carries information.

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

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

With a full output schema, complete annotations, and 100%-documented parameters, the description only needed to supply the mutation semantics and immutability rules it does supply. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, giving a baseline of 3. The description adds only marginal semantics — why name can't change and that description is replaced wholesale — without adding format, length, or validation detail beyond the schema.

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

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

States a precise verb+resource ('Changes a participant's description') and immediately delineates what is NOT changed ('Name and kind never change'), which cleanly separates it from register_participant, list_participants, and the task/entry tools. An agent can pick this tool without opening the schema.

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

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

Usage is implied rather than stated: edit an existing participant's description, and do not attempt to rename. No sibling or alternative is named, and no precondition (e.g., participant must already exist via register_participant) is spelled out, though the schema's participant_not_found note partially covers that.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so safety is covered. The description adds genuinely non-obvious behavior beyond that: omitted fields are untouched, the key is immutable, and each changed field files a field_changed entry recording old and new values, with no entry for no-op values. It does not cover permissions or behavior on archived projects, so not a 5.

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

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

Two sentences, zero filler, and the mutation/secondary-effect facts are front-loaded before the audit-trail detail. Every clause carries distinct information.

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

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

An output schema exists, so return values need no explanation. For a simple field-update tool with annotations covering the safety profile and a fully documented schema, the description supplies all remaining context an agent needs: partial-update semantics, key immutability, and the journal side effect.

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, and the schema already documents the null/default omission semantics for title and description. The description adds one piece of meaning the schema lacks: the key never changes, i.e. it is an immutable selector. That is a small but real increment above 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?

States a specific verb (changes) and resource scope (a project's title and description), so an agent can tell it mutates an existing project rather than creating one. It does not explicitly contrast itself with adjacent siblings such as set_attribute or archive_project, but the purpose itself is 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?

Usage is only implied: you call this to rename/re-describe an existing project. There is no when-to-use versus when-not guidance, no mention of alternatives like set_attribute for non-title/description fields, and no statement about prerequisites such as project state. Adequate but clearly gapped.

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?

Goes well past the annotations (readOnly=false, idempotent=true, destructive=false) by disclosing side effects: which journal entries get filed (section_changed, field_changed, assignee_changed), that editing one check marks earlier verdicts outdated, and that taking over another participant's assignee notifies no one. This is exactly the behavioral context annotations cannot carry.

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

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

Front-loads the core semantic in the first sentence, then adds constraint and side-effect detail in two short paragraphs. Every sentence carries information, though the editability rule is stated twice (description body and schema).

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

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

An output schema exists and annotations cover the safety profile, so return values need not be described. The description fills in the lock/unlock workflow and journal side effects; only version/optimistic-concurrency behavior is left entirely to the schema.

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

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

Schema coverage is 67% and the nested TaskChanges definitions are already richly annotated (field-level editability, refusal codes, null-clears-assignee). The description restates the partial-update rule already present in the schema rather than adding new per-parameter meaning, 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?

States a specific verb and resource ('Changes the given fields of a task') and immediately adds the partial-update semantics that distinguish it from a full replace. It does not name a sibling like transition or move_task explicitly, but the scope is 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?

Explains the editability window ('Title, description and sections are fixed from `open` on') and routes the agent to `transition` as the way to unlock a locked task. That is real when-to-use guidance, though it stops short of explicit when-not-to-use this versus move_task/transition for status work.

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

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds real behavior the annotations cannot: blocking until a match or `timeout`, the 60s cap with `journal_wait_too_long`, that an empty page is not an error, and that no `seq` is ever too old. This is exactly the beyond-annotation context required.

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

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

Front-loads the core behavior and the scoping model before the alternative-tool routing at the end. Dense but every sentence carries information; only the multi-line wrapping slightly hurts scanability.

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

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

An output schema exists, so return values need not be described. For a 7-parameter, zero-required, blocking streaming tool the description covers pacing, continuation, narrowing, error conditions, and sibling routing — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema carries the syntax baseline. The description still adds value by explaining the continuation contract between calls ('continues from the `seq` of the last entry received') and how `task`, `types` and `timeout` combine for the answer-wait pattern, which is more than restating field docs.

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

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

Opens with a specific verb, resource, and the blocking behavior ('Returns journal entries after the sequence number `after`, waiting for new ones'). The final paragraph explicitly distinguishes it from siblings read_entries and read_project_entries, so an agent can route correctly without opening a schema.

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

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

Explains the stream model (all case entries in `seq` order), how to narrow it (`task`, `project`, `types`), the continuation pattern, and a concrete usage recipe ('With types=["answer"] and task, one call covers an answer expected within timeout'). It also names the alternatives for already-filed entries.

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