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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false), it discloses the crucial immutability trait: no call edits or deletes an entry, and corrections happen via a new entry referencing the old one in `refs`. It also surfaces failure modes (`entry_fields_invalid`). It does not flag the idempotency_key behavior that the annotation leaves implicit, but the compatibility with destructiveHint=false is consistent.

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 paragraphs: purpose first, immutability and correction second, sibling routing third. No filler and the most decision-relevant facts come first.

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

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

With a rich schema and an output schema available, the description supplies exactly the runtime facts the structured fields cannot: immutability, correction-by-reference, and the sibling-tool boundaries. The one slightly cryptic phrase is 'without payload', which could confuse an agent about whether `body` is expected.

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 meaning by explaining that `refs` is the correction mechanism for immutable entries and that an empty title is refused. This goes beyond restating parameter names, though the per-parameter detail still lives mostly in the schema.

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

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

The description opens with a specific verb+resource ('Files an entry') and enumerates the exact entry types it accepts. It explicitly separates itself from siblings by naming the categories that have their own tools (summaries, questions, answers, verdicts, resolutions).

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 names the alternative tools (`add_summary`, `ask`, `answer`, `add_verdict`, `resolve`) and reserves `add_entry` for the remaining kinds of records. It does not, however, explicitly route the caller away from `add_project_entry` or clarify project-vs-task entry choice, so the guidance is clear but not fully closed.

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

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

Annotations already declare the write/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds value beyond that: entries 'stay as filed' (immutability), the numbering is project-scoped, refs addressing via TRK#7, and the entry_fields_invalid failure mode. It does not restate the annotation fields, which is correct.

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 purpose then addressing then error behavior. Every sentence carries information, though the closing error paragraph partially duplicates what the schema's per-field descriptions already state.

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 purpose, addressing, immutability, and failure modes. What remains thin is explicit guidance on non-idempotent retries, though the idempotency_key param and idempotentHint=false together convey this.

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 all six parameters are already documented including the type enum and refs grammar. The description restates the entry types and error semantics rather than adding syntax not in the schema, so the baseline 3 holds.

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 in a project's case') and immediately scopes it against the sibling concept: an entry that 'concerns the project rather than one of its tasks'. An agent can distinguish this from add_entry 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?

Gives the selecting condition (project-level vs task-level entry) and names the sibling add_entry as the task-side analogue. No explicit when-not-to-use or exclusion list, but the contrast with task entries is a clear routing signal.

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

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

With annotations providing no positive behavioral hints, the description carries the burden, and it discloses meaningful behavior: empty parts are rejected with entry_fields_invalid, the index title comes from the first line of done, and final summaries are handled elsewhere. This goes beyond the schema's required-field checks.

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

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

The description is compact and front-loads the core purpose before adding behavioral and contextual details. The second paragraph on 'significant step' earns its place even if slightly abstract.

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 is complete for a tool with a rich 100%-covered schema and an output schema: it covers purpose, validation behavior, title derivation, content guidance, and the boundary with close_task. Nothing essential 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. The description adds value by clarifying the four-part structure, requiring none of them to be empty, and explaining that the first line of done becomes the entry title.

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 ('Files') and a specific resource ('a summary: the handover note of a case'), and further distinguishes it by defining the four non-empty parts. This clearly separates add_summary from sibling tools like add_entry and close_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 gives clear context on what constitutes a significant step and explicitly notes that the final summary is filed by close_task, an exclusion that prevents misuse. It does not explicitly name alternatives like add_entry, so it stops short of a 5.

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

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

Annotations only say this is not read-only/idempotent, so the description carries the behavioral burden. It discloses that the latest verdict replaces earlier ones, that failed verdicts are filed immediately like passed ones, and that earlier-pass verdicts persist without counting. That is substantive stateful behavior beyond what annotations or schema indicate.

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 purpose sentence is front-loaded and the second paragraph earns its place by explaining pass-scoping, replacement, and the close_task overlap. There is no filler or repetition of schema content.

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

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

Between the schema (parameters, errors, idempotency) and the description (pass semantics, replacement, close_task overlap), an agent has what it needs to call add_verdict correctly. The main gap is that prerequisites such as assignee permission are implied rather than stated, and the return shape is left to the output schema.

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

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

All five parameters are already fully described in the schema (100% coverage), including enums, defaults, errors, and idempotency semantics. The description adds lifecycle context but no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The opening sentence names a specific verb ('Files'), a resource ('outcome of one review check'), and a scope ('as run by the task's assignee within the current pass'). The closing note that close_task also takes verdicts helps an agent distinguish this tool from the sibling that handles verdicts during closing.

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

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

The description gives the operative context: verdicts only count if filed in the current pass, and earlier-pass verdicts remain but do not count. It also points to close_task as the sibling that takes verdicts together with closing, which implies the alternative. It stops short of an explicit 'use X instead when...' rule, so not 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?

All annotations are negative (false), so the description carries the full burden and it delivers: first answer closes the question while later answers append, neither question nor answer changes task status, and the tracker builds the title from the question reference. These are genuine behavioral disclosures beyond the annotations.

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

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

Three sentences (~50 words), with the core purpose front-loaded in the first sentence and the two remaining sentences dense with scope and side-effect information. No filler or repetition of schema content.

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

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

The description plus 100%-covered schema and output schema make the tool safely invocable on its own. However, the conceptual boundary between `answer` and conceptually adjacent siblings (`ask`, `add_verdict`, `add_entry`) is not clarified, so an agent working within the full 30-tool set still faces selection uncertainty.

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 fully documents all four parameters, baseline 3 applies. The description adds only marginal param-adjacent context (task-token scope, question reference for the title) and no syntax or format details beyond the schema.

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

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

States a specific verb+resource: 'Answers a question of the same task', with scope ('Any holder of a `task` token answers, in any task'). The claim that answers do not change task status implicitly distinguishes it from state-changing siblings like `resolve` and `close_task`, 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 use case is implied (respond to an open question in a task) and the 'does not change task status' line implicitly cautions against using it for state transitions. However, with 30 siblings including `ask`, `add_verdict`, and `add_entry`, no explicit when-to-use or when-not-to-use guidance is given, leaving selection largely 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?

Discloses rich post-archive behavior far beyond the four boolean annotations: the project and tasks freeze, all change types are refused with `project_archived`, reads still work, and the sole exception is `unlink` of a link. Even the edge case of an open archived task blocking `blocked_by` tasks and holding its parent is spelled out. The description aligns with the annotations (state-changing, non-idempotent, non-destructive), so there is no contradiction.

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

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

Three paragraphs of dense, correctly front-loaded information: purpose in the first sentence, then freeze semantics, the unlink exception, and failure modes. The length is justified by the genuinely complex archive behavior, though the `blocked_by`/parent-holding detail is quite deep. Nothing is redundant with the schema, and each section 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?

Covers preconditions (main token), side effects (case entry), post-conditions (freeze and refusals), the unlink exception, reversibility via `restore_project`, and error codes — all without needing to explain return values since an output schema exists. Nothing an agent needs in order to invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, with both `key` and `reason` already documented including error responses (`project_not_found`, `project_reason_required`) and the case-entry filing behavior. The description only restates that archiving is done 'with a reason', adding no meaning beyond what the schema provides. Baseline 3 is appropriate because the schema carries the parameter documentation.

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 with a reason and files an `archived` entry in its case.' The freeze semantics and the refusal-until-`restore_project` behavior make the operation unmistakable and distinguish it from siblings like `restore_project` and `update_project`.

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?

Describes the effect and preconditions of use — only a `main` token may archive, and an already archived project is refused. It names `restore_project` as the undo path and notes that open tasks need no closing, which implicitly tells the agent not to pre-close tasks. It does not enumerate explicit when-not-to-use alternatives beyond the already-archived refusal, so it falls just 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 are all false, so the description carries the burden and does so well. It discloses that no delivery happens ('the tracker delivers nothing'), that questions count toward `open_questions`/`open_blocking_questions`, and that they stay open until 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?

Three short paragraphs, with the core action in the first sentence and no filler. The additional sentences each add distinct information: delivery behavior, lifecycle/counters, and read alternatives.

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 rich schema and the presence of an output schema, the description covers all non-obvious behavioral context: no notification, lifecycle, counters, and when to use read tools instead. No important decision-relevant behavior is missing.

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

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

The schema already documents every parameter with detailed descriptions, and the input schema coverage is 100%. The description adds a little lifecycle context around `blocking`, but does not need to compensate for schema gaps.

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 names a specific action and resource ('Files a question to registry participants'), and the rest clarifies lifecycle and counters. It distinguishes itself from the sibling `answer` by explaining a question remains open until an answer is filed, and from read tools by noting existing records are readable without asking.

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

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

It explicitly names `get_task` and `read_entries` as alternatives when the information is already recorded ('without a question'). It also explains the question lifecycle with `answer`, giving the agent a clear condition for when a follow-up tool is needed.

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 supply the safety flags; the description carries the real behavioral load: all-or-nothing semantics ('A refusal of any part files nothing and leaves the status as it was'), the post-filing order in which exit conditions are evaluated, and a side effect on other tasks ('Tasks this one blocked (`blocks`) lose the `blocked` feature, without an entry in their cases'). Retry behavior is disclosed via idempotency_key binding to the caller's token for 24 hours. The side effect on blocked tasks is a mild tension with destructiveHint=false but is not a contradiction (no data is destroyed and the behavior is fully disclosed).

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 action and atomicity in the first sentence, then failure semantics, then the downstream side effect. Dense but every paragraph earns its place; the only slight cost is that the trailing `blocks` paragraph reads as an afterthought rather than being surfaced earlier.

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 transactional, multi-part write with an output schema available, the description covers the failure modes, their error codes, ordering, idempotency and external side effects — everything an agent needs to decide and to interpret a refusal. Return-value detail is correctly omitted since an output schema exists.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds cross-parameter semantics the schema cannot express — the filing order (entries, then verdicts, then summary), that an empty verdicts list is legal because earlier verdicts count, and that the summary reports on the entries and verdicts preceding it. It does not duplicate enum or ref-format detail already in the schema.

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

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

Names a specific verb and resource ('Closes a task'), enumerates the ordered sub-operations (entries, verdicts, final summary), states the atomicity ('all in one transaction') and the exclusivity claim ('It is the only way into `done`'). An agent can distinguish this from add_entry, add_summary and add_verdict 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 the entry condition (the only path to `done`), the exact refusal conditions with their error codes (`checks_not_passed`, `task_has_unclosed_children`, `transition_not_allowed`, `entry_fields_invalid`), and one routing rule against a sibling ('a `failed` verdict sent here leaves no trace in the case, unlike one filed with `add_verdict`'). It does not systematically cover the other siblings (add_summary, transition), but the when/when-not guidance is concrete.

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

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

The annotations already indicate this is a write operation (readOnlyHint=false). The description adds a useful non-obvious behavioral constraint: only a `main` token may create projects. This goes beyond what the 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 compact with two short sentences and no filler. The first sentence is somewhat redundant with the tool name and schema, but the second sentence carries important auth context, so the overall structure is reasonably efficient.

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

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

For a simple create tool with a rich input schema and an output schema, the description covers the core operation and the critical auth constraint. However, it lacks routing guidance relative to sibling tools and does not describe any side effects beyond the annotations.

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

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

Schema description coverage is 100%, so the input schema already documents all four parameters in detail. The description merely echoes key, title, and description and adds no additional semantic value beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Creates a project', and names the main attributes (key, title, description). It is clear but does not explicitly distinguish itself from sibling tools such as update_project or create_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?

No guidance is given on when to use this tool versus alternatives. The note that only a `main` token creates projects is an authorization precondition, not a routing guideline for choosing create_project over create_task or update_project.

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 provide no safety hints (readOnly=false, idempotent=false), so the description bears full responsibility for behavioral disclosure. It clearly states the new task's status, the parent-child linking effect (files `link_added`), and the response containing the key. It also mentions the `task_fields_invalid` error for empty title/description. However, it does not cover idempotency behavior or retention of keys, which the schema documents but the description omits. For a mutating create operation, this is reasonable coverage but not exhaustive.

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

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

The description is structured into four paragraphs, each serving a distinct purpose: initial status, parent behavior, child-task rationale, and response/error. It is not overly verbose, but the third paragraph on when child tasks are appropriate is quite detailed and somewhat tangential to the core creation task. Overall, each sentence contributes useful information, though it could be tightened slightly.

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

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

The tool has 8 parameters (3 required) and an output schema, so the description need not restate return values. It covers the essential behavioral context: default status, parent-link behavior, and an error condition. It does not explain the `sections` parameter's role in transitioning to `open` (though the schema covers this), nor does it mention idempotency. Given the complexity, the description is mostly complete for an agent to correctly invoke the tool, with minor gaps filled by 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%, establishing a baseline of 3. The description adds meaningful semantics beyond the schema by elaborating on the `parent` parameter's behavioral implications (the link event, the parent_entry in response, and the rationale for child tasks). It also highlights that an empty title or description triggers a specific error, which relates to the required parameters. This extra context raises the score to 4.

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

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

The description opens with an explicit verb and resource ('Creates a task') and immediately states the initial status ('in `backlog`; a new task starts in no other status'). It clearly distinguishes from siblings like update_task, transition, and close_task by focusing on creation semantics. The specific scope (project, parent, sections) is also hinted, making the purpose unambiguous.

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

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

The description implicitly signals when to create a task (to start work in backlog) and provides detailed guidance on using the `parent` parameter to create child tasks under specific conditions. It does not explicitly name alternatives like update_task for modifications, but the creation purpose is so obvious that an agent can infer appropriate usage. The explanation of when child tasks are appropriate adds context, though it lacks explicit 'when-not-to-use' statements.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by specifying the return structure (key, title, description, attribute values, case index), but does not go deeper into behavior like pagination, authentication, or error handling beyond what the schema already notes for the key parameter.

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

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

Two sentences, front-loaded with the core purpose and return fields. The second sentence provides a useful pointer to list_projects without waste. Every word earns its place.

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

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

Given a single required parameter, high schema coverage, an output schema, and annotations covering safety, the description is quite complete. It lists the returned fields and how to obtain the key. Minor omission: it doesn't explicitly state fallback behavior for invalid keys, but that is covered in the schema's parameter description.

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

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

The input schema has 100% coverage: the key parameter is described with its meaning, case-insensitivity, and error behavior, plus an example. The description only repeats 'by its key' without adding any new semantic detail, so it does not exceed the schema's documentation. Baseline of 3 is appropriate.

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

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

The description states a specific verb ('Returns') and resource ('one project by its key'), and enumerates exactly what is returned (key, title, description, attribute values, case index), making it distinct from siblings like list_projects or update_project. It also references list_projects for obtaining keys, further clarifying scope.

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

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

The description implicitly conveys when to use this tool: when you have a project key and want its details. It explicitly points to list_projects for retrieving keys, giving context for the required input. However, it doesn't explicitly state when not to use it (e.g., for bulk retrieval) or mention other alternatives beyond list_projects.

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 flag readOnly/idempotent/non-destructive; the description goes further by explaining structural relationships (`parent`/`children` absent from `links`), that remarks have no side effects, and that `transitions` are unvalidated targets. No contradiction.

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

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

The description opens with a one-sentence summary, then groups related clarifications into paragraphs. Each sentence conveys a distinct behavioral or routing fact; no filler.

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

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

For a task-detail tool with a rich output schema and four annotations, the description is complete: it covers composition, relationships, boundary conditions for entries, side-effect-free remarks, and transition semantics. It leaves return-field definitions to the output schema.

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

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

The input schema already provides 100% coverage for `key`, including format, case-insensitivity, alias behavior, and `task_not_found`. The description adds no parameter-level detail, 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 ('Returns') and a specific resource ('everything about one task'), enumerating the principal content fields. The comprehensive singular-task scope clearly distinguishes it from search_tasks and read_entries.

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

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

Explicitly routes to `read_entries` for entries beyond the summary's `no` and for entry bodies, and to `transition` for actual transition checks. This gives an agent clear conditions for choosing alternatives.

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

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

The description substantially exceeds the annotations by disclosing concrete side effects and failure modes: it files `link_added`, refuses duplicate links with `link_exists`, rejects cycles with `link_cycle_detected`, blocks self-links, enforces the single-parent rule with `task_has_parent`, raises the `blocked` feature, and applies `task_closed` restrictions. This gives the agent a strong behavioral model beyond `readOnlyHint: false` and `destructiveHint: false`.

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

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

The description is dense but well organized into topical paragraphs: basic link semantics, hierarchy, blocking, closed-task behavior, and lineage. The core purpose is front-loaded in the first sentence, and every paragraph adds necessary behavioral detail without filler or repetition.

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

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

Given the tool's complexity, the description fully covers what an agent needs: accepted kinds, directional semantics, side effects, error conditions, hierarchical constraints, blocker behavior, and closed-task limitations. An output schema exists, so the lack of explicit return-format detail is not a gap.

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

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

The schema already covers all parameters with high detail, so the baseline is 3. The description adds meaningful semantics by explaining the directional meaning of `kind`, how `parent`/`child` are represented in `get_task`, and how idempotency interacts with repeated calls. It does not add much about the `other` parameter, but the schema already defines it clearly.

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

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

The description opens with a specific verb and resource: 'Links two tasks', and immediately distinguishes the operation from its inverse sibling `unlink` by explaining that a link is stored once and the same link from the other side is refused. It also enumerates the distinct link kinds, making the tool's purpose unambiguous.

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

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

The description gives contextual guidance on when each `kind` is appropriate, especially for closed tasks ('accepts only `relates`') and for hierarchy links (`parent`/`child`). It also clarifies that only a real link shows lineage, not a key mentioned in an entry body or `refs`, which helps agents choose this tool over other ways of referencing tasks. It does not explicitly name alternatives like `unlink`, but the conditions are clear enough.

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 read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond annotations by revealing the inclusion/exclusion rule for temporary agents and framing the registry as question addressees, which is not visible in the schema or annotations.

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

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

The description is two sentences with no redundancy. The primary purpose is front-loaded, and the temporary-agent exclusion earns its place by adding scoping information that is essential for correct usage.

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

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

For a simple read-only list tool with fully documented optional pagination parameters, an output schema, and strong annotations, nothing essential is missing. The description covers the domain context and the key exclusion rule, making the tool's behavior predictable.

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

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

Schema description coverage is 100% for both parameters (limit and cursor), so the description carries no additional parameter burden. The baseline of 3 applies; the description adds no special semantics beyond what the schema already documents.

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 ('Lists the participant registry') and precisely defines the scope: humans and permanent agents who are possible addressees. It also distinguishes itself from register/update_participant by clarifying what is listed versus what is maintained.

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 clarifies when this tool is appropriate: to view the registry of possible question addressees, and it explicitly notes that temporary agents are absent. While it doesn't name alternative tools or exclusion conditions explicitly, the scope is clear enough for an agent to choose it over participant mutation tools.

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

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

The annotations already cover read-only, idempotent, and non-destructive behavior, so the description adds useful behavioral context rather than repeating safety traits: it discloses pagination ('one page at a time'), the returned field subset, and that descriptions are intentionally excluded and available via get_project. This is sufficient and complementary.

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

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

Two sentences carry purpose, pagination behavior, field scope, and a pointer to the sibling tool for descriptions. Every sentence earns its place; no fluff or repetition.

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

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

The tool is a simple read-only listing with no required parameters and a full input schema, an output schema, and safety annotations. The description adds the remaining context needed for correct use: paging, returned fields, and the route to get_project for descriptions.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds no parameter-level detail beyond what the schema already documents for limit, cursor, and include_archived. It therefore neither harms nor materially compensates for the schema, remaining at the baseline.

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

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

The description uses a specific verb ('Lists'), targets a specific resource ('the installation's projects'), and scopes the result to one page with key, title, and archive time. This clearly distinguishes it from related tools like get_project, which the description explicitly reserves for project descriptions.

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: this is the paged listing of projects, not the detailed view. It names get_project as the tool for descriptions, which is an explicit when-not for that use case, though it doesn't enumerate other sibling alternatives.

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

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

Annotations only provide generic hints (readOnly=false, destructive=false, etc.), so the description carries the behavioral disclosure burden. It does so extensively: renumbering, `previous_keys`, preservation of status/sections/links/parent/children/case, closed-task moves, frozen-project failures, partial batch moves, and whole-call refusals. There is no contradiction with the annotations.

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

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

The description is dense but every sentence earns its place. It front-loads the core action, then methodically covers single moves, batch behavior, error codes, and atomic refusal conditions without filler. The paragraph structure aids scanning.

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

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

Given the tool's complexity, the description is complete: it covers auth scope, single and batch moves, key reissuing, preservation of task properties, frozen-project errors, response `results`, and whole-call refusals. Since an output schema exists, the description need not enumerate the full return shape beyond `results`.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. It explains that previous keys keep addressing the task, that a task holds at most one key per project, how list order determines new numbers, and the exact per-key versus whole-call error semantics. This is far more than the schema descriptions alone provide.

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

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

The first sentence states a specific action and resource: 'Moves a task to another project' and distinguishes the operation by detailing recording of the move and the `moved` entry. The description further clarifies scope with 'One key moves one task' and behavior for frozen projects, leaving no ambiguity about what the tool does.

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

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

The description provides clear context for when to use the tool: moving tasks between projects, including closed tasks and batch moves. It notes the `main` token requirement and the `project_archived` failure condition, but it does not explicitly name alternatives or state when not to use this tool versus a sibling.

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

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

Beyond the readOnly/idempotent annotations, it discloses ordering ('in number order'), payload inclusion, AND-combination of filters, and the semantic content of decision/attempt entries, including failed attempts. That is genuinely useful behavioral context that the annotations and schema do not state.

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 main capability is front-loaded in the first sentence; the remaining paragraphs add filter semantics, type semantics, and the sibling alternative with no repetition or filler. Every sentence earns its place.

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

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

With a complete input schema, strong annotations, and an output schema, the description supplies the missing semantics: ordering, filter combination, type meanings, and the boundary with wait_journal. No critical behavioral or routing information is 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 coverage is 100%, so the baseline is 3. The description adds value by explaining how types and after_no combine under 'and' and by giving the meaning of decision/attempt entries, which goes beyond individual property descriptions. It does not need to restate key/limit/cursor.

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

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

The description opens with a specific verb and resource: 'Returns entry bodies of one task's case, with payload, in number order.' This clearly separates it from wait_journal (many cases in one stream) and, by scope, from read_project_entries. The filter examples reinforce that this is the single-task entry reader.

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

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

It explicitly routes multi-case streaming reads with waiting to wait_journal, and the filter examples ('types=... gives every summary', 'after_no...') teach how to narrow a call. It does not explicitly name read_project_entries as the project-wide alternative, though the 'one task's case' scope makes the boundary reasonably clear.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond those hints: ordering by entry number, payload inclusion, filter conjunction semantics, the attribute-history special case, and the fact that the case index is only available 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?

The description is compact and front-loaded with the primary behavior. Each sentence earns its place: result content, scope/context, filter semantics, attribute behavior, and relationship to get_project. No redundant phrasing.

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 7-parameter read tool with a full input schema, an output schema, and rich annotations, the description covers ordering, payload inclusion, filter combination, attribute filtering, and where to get the case index. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters well. The description still adds value by explaining that filters combine with 'and', that attribute gives a specific attribute's history, and that the relevant entry types are attribute_created, attribute_changed, and attribute_removed.

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

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

The description names a specific verb and resource: it returns the bodies of a project's case entries, payload included, ordered by entry number. It also distinguishes itself from siblings by scoping to the project's case and explicitly pointing to read_entries and get_project for related behavior.

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

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

It clearly frames when to use this tool: to read project case entries, including attribute history. It also explains how filters combine and routes the case index to get_project. It doesn't explicitly state exclusions versus read_entries, but the project-scope wording makes the boundary reasonably clear.

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

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

Annotations already declare readOnlyHint=false (mutation) and idempotentHint=false, so the description does not need to repeat that. It adds valuable context: the requirement for a `main` token and that the token is issued via REST API, which are behaviors not covered by annotations. This supplements the annotation profile without contradiction.

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

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

The description is two sentences with no filler. The first sentence states the core purpose, and the second sentence adds a constraint and differentiates from a sibling tool. Every clause earns its place, and the most important information is front-loaded.

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

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

Given the tool's moderate complexity (4 params, output schema present, minimal annotations), the description covers the essential purpose, token issuance, and differentiates from update_participant. It does not explain return values, but the output schema handles that. It omits potential side effects beyond token issuance, but that is a minor gap; an agent can call it correctly with the information provided.

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

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

The input schema has 100% description coverage for all four parameters, including detailed explanations of `name`, `description`, and `idempotency_key`. The description adds no additional parameter-level semantics, so it neither improves nor degrades what the schema already provides. The baseline of 3 applies.

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

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

The description states a specific verb ('Registers') and resource ('a human or a permanent agent'), and explicitly differentiates itself from update_participant by noting that an existing participant's description is changed by that tool. This makes it unmistakable that register_participant is for creating new participants, distinguishing it from siblings like update_participant and list_participants.

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

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

The description gives a clear usage condition: only a `main` token can register participants, and the new participant's token is issued via the REST API. It also points to update_participant for changing descriptions, implying this tool is for new registrations. However, it does not explicitly list when not to use it or fully describe alternative selection criteria, leaving some room for 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?

The description discloses important behaviors beyond the annotations: history stays in the case, a later set_attribute recreates the attribute, missing attributes are refused, and a task token is required. This adds genuine context that the false annotation hints alone do not provide.

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

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

The description is concise and well-structured: the main behavior and side effect come first, followed by persistence semantics and error/token constraints. Every sentence earns its place with no filler.

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

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

The description covers the operation, side effects, persistence, error cases, and authentication context. Since an output schema exists, return-value details need not be described, and nothing essential appears missing.

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

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

The input schema already documents all parameters with validation details and error behavior, giving 100% schema description coverage. The tool description adds little parameter-specific meaning beyond referencing the reason and last value, so the baseline of 3 is appropriate.

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

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

The description states a specific action and resource: 'Removes a project attribute' and the side effect 'files an attribute_removed entry'. This clearly distinguishes it from siblings such as set_attribute and update_project.

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 use case is implied by 'Removes a project attribute' and the error conditions, but the description never explicitly says when to choose this over set_attribute or other siblings. It does provide useful context about the required task token and the attribute_not_found condition.

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

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

The annotations provide only basic safety hints, so the description carries the burden of behavior. It discloses key state transitions: any outcome removes the remark from open_remarks, accepted keeps it in remarks_in_work until continuation closes, and title generation rule. This goes well beyond structured data.

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

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

Three sentences, each earning its place: purpose, behavioral nuance, and title rule. Front-loaded with the core action, no filler or redundancy.

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

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

The tool has moderate complexity with six parameters and outcome-dependent behavior, but the schema and output schema cover the details. The description explains the essential state effects needed to call it correctly; it does not repeat schema content. A 4 reflects that it is complete for practical use, though it could theoretically mention more about accepted-task linkage.

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 schema already documents every parameter with detail, including the outcome enum semantics and the task parameter's constraints. The description reinforces the outcome/task connection but does not add new parameter-level meaning; the baseline of 3 applies.

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

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

The description opens with a specific verb+

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

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

The description clearly identifies the context (resolving remarks) and the outcome-specific behaviors, which gives a clear sense of when to use it. However, it does not explicitly name alternatives or state when not to use it, so it stops short of the highest bar.

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

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

Annotations indicate a write operation (readOnlyHint=false) but not destructive (destructiveHint=false). The description adds behavior beyond that: filing a 'restored' entry with the reason, resuming tasks, and the token restriction. No contradiction with annotations found.

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

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

Two short, dense paragraphs. The primary action and effect are in the first sentence, with a token restriction and an error condition in the second. No filler or redundancy; every line 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?

For a tool with two required params, an output schema, and annotations, the description covers the core behavior, side effects, a permission restriction, and a common error. It does not describe return values, but the output schema exists. Minor gap: it doesn't address what happens if a project is already restored, but that is not critical for correct invocation.

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

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

Schema coverage is 100%, so both 'key' and 'reason' are already documented with examples and error handling. The description mentions the reason is filed in the entry, but that is also in the schema's reason description. It adds no additional meaning beyond the schema, so baseline 3 applies.

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

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

The description uses a specific verb ('Brings back') and resource ('an archived project'), and describes observable effects (files a 'restored' entry, tasks resume). This clearly distinguishes it from siblings like archive_project without requiring the agent to infer the 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?

It gives explicit conditions: only a 'main' token can restore, and non-archived projects are refused with a specific error. It does not name alternatives directly, but the inverse relationship with archive_project is clear from context. The token restriction and error case provide practical guidance for when the tool applies.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behaviors: conditions combine with 'and', archived projects are excluded unless explicitly named, default ordering by key, truncation markers for long text, and specific error codes for invalid fields, operators, or values. This substantially exceeds what annotations alone 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?

Although the description is long, it is dense and every sentence earns its place given the tool's complexity. The structure is logical: core purpose first, then combination semantics, scoping behavior, ordering, truncation, and error handling. No fluff or repetition.

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

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

The description covers edge cases, error semantics, archived-project behavior, ordering defaults, and distinguishes single-task retrieval via get_task. An output schema exists, so return-value documentation is not required from the description. For a 17-parameter search tool, this is complete and actionable.

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 each parameter already has a rich description, so the baseline is 3. The description still adds meaning beyond the schema by explaining how query and separate condition parameters combine, how archived projects are handled, and how ordering and truncation behave across results.

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

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

The description opens with a specific verb and resource: 'Searches tasks by a query language string, by separate conditions, or by both.' It clearly distinguishes itself from the sibling get_task by noting that a single task in full is returned by get_task, and it conveys the search scope without ambiguity.

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

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

The description gives clear context on when search_tasks is appropriate: searching by query language, separate conditions, or both, and it explicitly routes full-task retrieval to get_task. It does not enumerate exclusions for every sibling tool, but it provides enough directional guidance for an agent to select the right tool.

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

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

Beyond the annotations, the description discloses meaningful side effects: filed entries (`attribute_created`, `attribute_changed`), preservation of the previous value, no-op behavior on identical values, and case-insensitive addressing that never renames. It also explains that the tracker stores attributes as inert text and does not interpret or search them, which is valuable behavioral 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?

The description is front-loaded with the core purpose, then uses a compact bulleted list to lay out the state transitions. Each sentence contributes either to the conceptual model or to operational behavior; there is no filler or unnecessary repetition.

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

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

Given the tool's complexity, the description covers every meaningful behavioral case: creation, update, no-op, entry filing, reason requirements, naming semantics, and lack of type/search interpretation. The output schema and rich input schema handle return values and parameter formatting, so nothing essential is missing for correct invocation.

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

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

The schema already provides 100% parameter coverage, but the description adds useful semantic nuance: the name keeps its original spelling and a different spelling addresses the same attribute without renaming it. It also reinforces when `reason` is required versus optional, complementing the schema's parameter descriptions.

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

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

The description names the exact operation ('Sets the value of a project attribute') and clarifies what kind of attribute is meant ('a reference fact of the project such as its repository or main branch'). It also states the create-or-change duality, making the tool's purpose distinct from sibling tools like remove_attribute.

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

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

The description gives clear usage context by explaining the three possible states (absent, different value, same value) and the resulting behavior. It does not explicitly name alternatives or say 'use this instead of remove_attribute', but the scope and constraints ('Attributes carry no types and no search') provide enough practical guidance for an agent to select it appropriately.

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

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

Beyond the all-false annotations, the description discloses many side effects and invariants: waiting is never moved automatically, entering in_progress starts a new pass, cancelled clears the blocked feature on dependent tasks without adding an entry, and the response includes the new status, version, and status_changed entry number. This is exactly the behavioral context an agent needs.

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

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

Although dense, the description is front-loaded with the core action and every subsequent sentence carries distinct information about refusals, side effects, or response shape. No filler or redundant restatement of the schema is present.

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

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

For a state-transition tool with an output schema, the description covers allowed targets, refusal codes, side effects, caller responsibilities, and response contents. An agent has enough information to decide when to call it and what to expect, including the close_task alternative.

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 description adds extra meaning: it explains that for waiting the reason is 'the only record of what the task waits for' and ties refusal conditions to specific target statuses. The main description does not need to repeat the schema's parameter documentation.

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 'Moves a task to another status along the fixed transition table' states a specific verb and resource and immediately scopes the operation to a predefined table. It further differentiates from the sibling close_task by saying a move to done is not a transition and 'a task is closed by close_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 gives explicit refusal conditions that tell an agent when the transition cannot be performed, and names close_task as the alternative for closing. It also states who must perform certain transitions ('both moves are the caller's') and when reason is required, giving clear usage context.

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

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

Annotations are all false and provide no safety or idempotency context, so the description carries the full behavioral burden. It discloses the success event (`link_removed`), symmetric matching from either side, closed-task exceptions (`parent`/`blocks` stay, `relates` removed), and the failure response (`link_not_found`). This is substantial and honest 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 description is three dense sentences with no filler. The first sentence states the action and observed outcome, and the next two handle symmetric matching and important exceptions. Every sentence earns its place.

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

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

For a mutation tool with an output schema, this description covers the main success path, a key closed-task behavior, and the primary error case. Minor gaps remain, such as explicit closed-task behavior for `child` and `blocked_by` and any permission requirements, but an agent can still call the tool correctly with high confidence.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by explaining that `blocks` and `blocked_by` describe the same underlying link and that direction matters relative to `key`/`other`. This goes beyond the schema's field descriptions, though the schema already documents the core parameter roles.

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: 'Removes a link'. It distinguishes itself from the sibling `link` (which presumably creates links) by describing removal and even notes the symmetric `blocks`/`blocked_by` naming. The core purpose is immediately clear and unambiguous.

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

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

The description gives a clear context for when to call the tool: whenever a link should be removed. It covers edge cases like closed tasks and missing links, but it does not explicitly name alternatives or provide an exclusion like 'use link to create a link instead'. This is clear context without full alternative routing, so a 4 fits.

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 key behavioral context beyond annotations: only a main token can edit, name/kind are immutable because the name signs entries already filed, and the previous description is not kept. This clarifies and extends the destructiveHint annotation with specific consequences.

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

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

Three concise sentences with no filler. Front-loaded with the primary action, then each subsequent sentence adds a distinct piece of information: permission, immutability, and destructiveness. Every sentence earns its place.

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

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

Complete for a simple two-parameter update tool. The description covers the permission requirement, immutability of name/kind, and the destructive nature of overwriting. An output schema exists, so return values are not needed. No critical information is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal parameter-level detail beyond the schema, only referencing the description field and the immutability of name/kind, which does not substantially enhance parameter understanding.

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

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

States a specific verb (changes) and resource (participant's description), and distinguishes itself by explicitly saying name and kind never change. This differentiates it from any potential create/update participant tools and clarifies its scope.

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

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

Implies usage for updating participant descriptions and gives a clear prerequisite (only a `main` token can edit). It also provides an exclusion (name and kind never change), which helps agents understand what not to attempt. Lacks explicit naming of alternative tools, but no direct sibling for this action exists in the list.

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

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

The description adds substantial behavioral detail beyond the annotations: partial-update semantics, the requirement for a `main` token, the key never changing, event-log entries with previous/new values, and no-op behavior when values are unchanged. These are exactly the non-obvious traits an agent needs to predict side effects.

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

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

Three sentences, each carrying necessary information: the core action, the authorization constraint, and the event-log side effects. Important behavioral facts are front-loaded before lower-level details.

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 three-parameter tool with a full output schema, rich annotations, and schema descriptions for all parameters, the description covers the remaining behavioral essentials: authorization, partial updates, immutability of the key, and event recording. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining that omitted fields stay unchanged, equal values file no event, and the key is immutable — details beyond the schema's property descriptions and examples.

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

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

The description names a specific verb ('Changes'), a specific resource ('a project'), and the exact fields affected ('title and description'). This clearly distinguishes update_project from sibling tools like update_task and update_participant without needing to inspect 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?

The description makes it clear this tool is for editing project title and description, which is sufficient context for selecting it. It does not explicitly name alternatives or exclusion conditions, but the resource and field specificity separate it from siblings.

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

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

Beyond the annotations, the description discloses important side effects: each changed field files `section_changed` or `field_changed`, assignee changes file `assignee_changed`, and editing a check marks earlier verdicts as `outdated`. It also reveals the editability constraint based on task state, which annotations alone do not convey.

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

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

The description is compact and front-loaded: the core behavior is in the first sentence, followed by state constraints and then side effects. Every sentence contributes unique, decision-relevant information without repetition or filler.

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

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

The description covers the operational workflow, editability constraints, and behavioral side effects, while the schema and output schema handle field-level details and return structure. An agent has enough information to decide when to call this tool and what to expect from doing so.

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

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

The schema already documents most parameters richly, including nested field meanings and constraints. The description adds value by explaining the partial-update contract and field-editing restrictions, which helps interpret the `changes` parameter even though the top-level parameter itself lacks a direct schema description.

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

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

The description opens with 'Changes the given fields of a task; fields left out stay as they are,' which clearly identifies the verb (change), the resource (a task), and the patch semantics. It is distinguishable from siblings like create_task, transition, and move_task because it is explicitly about field-level edits rather than state changes or creation.

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

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

The description gives concrete guidance on when this tool is and is not appropriate: title, description, and sections are fixed from `open` onward, and editing them for tasks past `backlog` requires the transition-back/edit/transition-forward workflow. It does not explicitly name sibling alternatives, but it provides enough workflow context to steer an agent correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains the waiting semantics, the continuation behavior ('The next call continues from the `seq` of the last entry received'), and the non-error empty page after timeout. It also clarifies that entries are permanent and no `seq` is too old. This is more than the annotations alone provide, though it doesn't detail pagination or cursor behavior in depth.

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

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

The description is compact and front-loaded. The first sentence states the core function immediately. The second paragraph adds necessary context about the journal stream and sibling tools without redundancy. Every sentence earns its place, and the description is appropriately sized for a tool with 7 parameters and complex waiting semantics.

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

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

Given the tool's complexity (waiting semantics, filtering, pagination, continuation), the description is complete. It covers the stream model, filtering options, timeout behavior, continuation, and distinguishes from sibling tools. The output schema exists, so return values are documented elsewhere. The description provides everything an agent needs to decide when to call this tool and what to expect.

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 7 parameters thoroughly. The description adds meaningful context beyond the schema: it explains the overall stream semantics, how `task`, `project`, and `types` narrow the stream, and the practical use case for `types=["answer"]`. It doesn't repeat parameter-by-parameter details, which is appropriate given the schema's completeness, but it does add cross-parameter context that helps an agent understand how the parameters interact.

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

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

The description clearly states the tool's function: 'Returns journal entries after the sequence number `after`, waiting for new ones.' It specifies the resource (journal entries), the operation (wait and return), and the key parameter (`after`). It also distinguishes itself from siblings by noting that entries filed in one case are returned by `read_entries` and `read_project_entries`, which helps an agent differentiate it from those alternatives.

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

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

The description provides explicit usage context: it explains the journal is a single stream of all case entries, how `task`, `project`, and `types` narrow it, and when the call returns (as soon as a matching entry appears or after `timeout` seconds). It also gives a concrete use case: 'With `types=["answer"]` and `task`, one call covers an answer expected within `timeout`.' This is strong guidance for when to use this tool.

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