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

The description adds substantial behavioral context beyond annotations: non-idempotency and retry risk, OpenProject <16.0 behavior for internal comments, and the distinction that notify=false only suppresses notifications while the comment remains visible. These are exactly the operational caveats an agent needs before invoking a write operation.

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

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

The description is front-loaded with the core action and usage cases, then organized into pitfalls and cross-references. Despite covering several caveats, every section earns its place and remains easy to scan.

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

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

The tool has an output schema and annotations, and the description still adds valuable return-shape context, retry guidance, version-specific caveats, and sibling routing. Nothing an agent needs to invoke it correctly appears to be 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 parameter meanings are already fully documented in the input schema. The description reinforces important semantics for internal and notify, but it does not add substantial new syntax or format guidance beyond what the schema already provides.

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

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

The description states a specific verb and resource: post a comment on a work package. It also distinguishes the tool from siblings by naming update_work_package, list_work_package_comments, and upload_attachment as alternatives for related tasks.

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 when-to-use cases (reply in a thread, record a decision, leave a handover note) and routes other actions to the correct sibling tools. It also warns against blind retries and points to list_work_package_comments for reading the thread first.

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

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

Goes well beyond the annotations: discloses the 422 error and the 'user' violation when the target can't see the work package, the differing permission requirements for adding yourself vs others, and the idempotent 'changed: false' behavior on repeat calls. It also describes the return payload (watcher id/name, watch state, changed flag) even though an output schema exists.

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

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

Front-loaded purpose sentence followed by labeled sections (Pitfalls, Cross-references) that make scanning easy, and every sentence carries actionable content. It is on the long side and some return-value detail is slightly redundant with the output schema.

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

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

Covers purpose, preconditions, permission model, idempotency, error modes, and neighbors — everything needed to call a two-parameter mutation correctly. Return values are explained even though the output schema already carries them.

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 meaning by tying user_id validity to visibility of the work package and permission scope. It doesn't add id-format or type details beyond the schema, so it doesn't reach 5.

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 ('Subscribe a user to a work package's notifications') and immediately distinguishes it from assignment ('Watching is not assignment'). An agent can tell it apart from update_work_package or remove_work_package_watcher without opening the schema.

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

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

Explicit when-to-use ('when someone should be kept in the loop... without being assigned'), explicit alternative ('use update_work_package(assignee=...) for that'), and cross-references to the reverse tool and to get_work_package(include=['watchers']) for checking existing watchers.

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

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

Goes far beyond annotations: preflight validation of all items before any write, sequential but non-atomic execution, partial_failure reporting, item notes for values OpenProject ignores (story_points without Backlogs), unknown-outcome semantics implying a possible post-commit server failure, no auto retry/rollback, and a warning never to rerun successful items. This is a materially richer disclosure than destructiveHint=false/idempotentHint=false provides.

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 dry-run contract and every sentence carries operational content, including the subtle anti-retry warning. It is a dense single paragraph, though, which makes the review-then-apply procedure harder to scan than a short sequence would be.

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

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

An output schema exists, so return values need not be explained, yet the description still covers result reporting (per-item results, partial_failure, item notes) and the lock_version round-trip. For a high-risk batch mutation this is complete enough 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?

Explains the semantics that matter most: omitted fields untouched, null clears clearable fields, target_versions=[] clears assignments, and notify applies to the whole batch. Schema coverage is 67%, and fields like custom_fields and percentage_done remain undocumented in both places, so it does not fully compensate for the gap.

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

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

States a specific verb (preview/apply), resource (work-package updates), and batch scope (up to 50, each with its own changes). This clearly distinguishes it from update_work_package, the single-item sibling.

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?

Prescribes an explicit two-phase workflow: dry_run=true first, review diffs and validation errors, then resubmit with dry_run=false and each preview's lock_version. It also states the recovery path (correct failing items or submit a valid subset) and says status/type/priority follow update_work_package semantics.

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 cover only the read/write and idempotency profile; the description adds the crucial asynchronous behavior (queues a job, returns {scheduled, job_id, status, message, notes}), the polling contract, the fact it never claims the copy exists, the 403 permission cause, and that relations copy but time entries and comment histories do not. This is exactly the context annotations cannot carry.

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

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

Front-loaded with the core action, then clearly segmented into async behavior, pitfalls, and cross-references. Slightly verbose in places (the 'spin a new engagement' framing, the repeated polling advice) but nearly every sentence adds an operational fact.

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?

Even though an output schema exists, the description explicitly describes the return shape and the polling loop, plus permission requirements and data-fidelity limits. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: only include_work_packages and notify are exposed while other copy flags (members, versions, wiki, boards, file links) fall back to instance defaults, so the copy may contain more than the two booleans imply. The id_or_identifier 'template, not the copy' clarification is also reinforced.

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 ('Copy a project — its settings, and optionally its work packages — into a new one') and immediately differentiates it from sibling create_project later on. An agent can distinguish it from update_project/create_project without opening the schema.

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

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

Gives the template/engagement scenario for when to use it, plus explicit alternatives: create_project 'makes an empty project instead', update_project 'renames the copy afterwards', get_job_status follows the job. Permission conditions for a 403 are also spelled out.

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

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

Annotations already declare this as a non-idempotent write, but the description adds real substance beyond them: the pre-commit form validation that surfaces `violations` per attribute, the fact the derived identifier is committed verbatim, the 403-is-an-account-problem pitfall, default modules/types enabled on creation, and that members are not inherited from the parent. That is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the verb and the key differentiator, then organized into usage, returns, pitfalls and cross-references — dense but navigable. It is somewhat long, and the listed return fields partly duplicate the output schema, which costs a point.

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 6-param mutation with permissions implications, the description covers creation modes, validation behavior, failure semantics, post-creation caveats and related tools. Output schema exists yet the description's return-value hint (keep the id, identifier also accepted) adds routing value rather than pure redundancy.

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 every parameter richly, which sets the baseline at 3. The description largely restates schema content (identifier derivation, status codes, parent permission) rather than adding param-level meaning the schema lacks.

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

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

States a specific verb and resource ('Create a project') and immediately distinguishes itself from siblings by noting the two-phase form-endpoint validation ('POST /projects/form before committing'). An agent can tell it apart from copy_project or create_work_package without opening another 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?

Explicitly covers the two usage modes (top-level workspace vs. subproject via parent_id) and the cross-references section names the alternatives and their roles — list_projects to find the parent, update_project to change fields afterwards, get_project_metadata to inspect types/versions. It also gives a when-not condition implicitly via the 403 permission caveat.

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

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

Annotations already declare write semantics (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the safety profile is covered. The description still adds real value: the POST /versions/form preflight that surfaces 'violations', the 'manage versions' permission and what a 403 means, and the per-project scoping of sharing. That is solid added context beyond the annotations, though return-format detail is already handled by the output schema.

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

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

Front-loaded with the core action and then organized into labelled paragraphs (return shape, pitfalls, cross-references), which is easy to scan. It is longer than necessary because the end_date pitfall and return fields are restated in both the description and the schema.

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

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

For a non-idempotent, open-world write tool with 7 parameters, the description covers permissions, failure semantics (violations vs opaque rejection), scoping rules and follow-up tools. With an output schema present, return values are additionally stated but not required, so nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by adding semantics the schema cannot express, such as end_date landing on the API's endDate field after an older client silently dropped it, and that the defining project cannot be changed afterwards. It also repeats some schema content (open vs locked/closed), which caps it below 5.

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

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

States a specific verb and resource ('Create a version') and immediately disambiguates the resource as 'release, milestone or sprint' inside a project. This distinguishes it cleanly from siblings like list_versions, update_version and delete_version.

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

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

Gives an explicit when-to-use ('open a new sprint or plan a release before assigning work packages') and routes the agent to alternatives: list_versions for existing ids, update_version to change dates or close, list_projects for the project id. Nothing is left to inference.

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

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

The annotations already declare the mutating, open-world, non-idempotent profile, and the description goes beyond them by disclosing the form pre-flight: invalid status, missing custom fields and disallowed types come back as structured violations with allowed values 'before anything is written', which tells the agent failures are safe. It also warns that unknown custom-field keys fail with the valid list. The gap is that it never states permission/auth requirements, and the return-value sentence partly duplicates the output schema.

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

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

Front-loaded with purpose and the pre-flight behavior, then use cases, returns, pitfalls and routing, with a labeled 'Pitfalls' block. Every sentence carries signal except the return-value summary, which restates what the output schema already gives.

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 21-parameter mutation with an output schema and full annotation coverage, the description supplies what structured data cannot: the validation flow, the name-vs-id convention split, custom-field prerequisites, and the correct sibling to use for updates and attachments. An agent has enough to call this correctly on the first attempt.

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

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

Schema coverage is 100%, so the baseline is 3, but the description synthesizes a rule the schema only states per-field: 'type, status and priority take names or ids; versions, assignees and parents need numeric ids.' It also directs the agent to get_work_package_schema for custom fields, which is real added meaning for the riskiest parameter.

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

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

States a specific verb and resource ('Create a work package') and immediately differentiates the flow from a plain write by noting it is validated through OpenProject's form endpoint first. The covered object kinds (tasks, bugs, subtasks via parent_id, milestones via date) let an agent separate this from update_work_package or create_work_package_relation without opening the schema.

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

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

Explicitly names the alternatives and the condition that selects them: 'To change it afterwards use update_work_package; to attach a file to an existing work package use upload_attachment.' It also scopes the creation use cases (subtasks need parent_id, milestones use date) so the agent knows which parameters select which behavior.

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

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

Goes well beyond the annotations: canonical direction rewriting on save (precedes A→B returns as B follows A with swapped from/to), single-relation-per-pair with a 409 on the second attempt, cycle rejection as a validation error, and the date-rescheduling side effect of follows. The only gap is that it doesn't say what permissions/visibility the account needs beyond 'must be visible to the account' in the schema.

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

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

Front-loaded with purpose, then a labelled Pitfalls block and a Cross-references block, so the agent can skim to what it needs. Slightly long and repeats the hierarchy warning in both the description body and the type parameter, but each section carries distinct information.

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

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

The description states the return payload (id, type, reverse_type, both work packages, lag, description) even though an output schema exists, and covers the three failure modes (409 duplicate, cycle validation error, direction rewriting) an agent must handle. Nothing needed to call this correctly for a 5-parameter mutation tool 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 earns extra by explaining that the returned from/to and type may not match what was sent, which changes how an agent should interpret from_id/to_id/type together. The lag constraint and enum meanings are already fully in the schema, so it does not restate them.

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

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

Opens with a specific verb+resource and enumerates the relation kinds (blocks, follows, duplicates, relates), then states the intent: recording a dependency the schedule or reader needs. It is clearly separable from siblings like update_work_package_relation and update_work_package (parent/child) 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?

Explicitly says when to use it ('to record a dependency the schedule or the reader needs to know about') with concrete example sentences, and routes the agent elsewhere where appropriate: get_work_package(include=['relations']) to discover existing links, update_work_package_relation to change one, delete_work_package_relation to remove, update_work_package(parent_id=...) for hierarchy.

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

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

Goes well beyond the annotations (destructiveHint/idempotentHint) by explaining that metadata is read before deletion so unknown ids fail first, that deletion needs edit permission (403 can follow a successful read), and that a repeat call returns 404 rather than succeeding. It also discloses the true blast radius — embedded references lose the file, and removing a file does not remove referencing comments or work packages.

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

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

Front-loaded with purpose and usage, then organized into return values, pitfalls, and related tools — every section is scannable. It is on the long side, but the sentences carry distinct, non-redundant information rather than padding.

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

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

For a destructive tool with an output schema, the description covers what an agent needs: preconditions, error semantics, irreversibility, permission requirements, and the correct sibling tools. No critical decision-relevant gap remains.

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

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

Schema coverage is 100% and both params are described there, so the baseline is 3. The description earns extra credit by clarifying the confirm-gate behavior pattern (confirmation_required, nothing read or deleted) and warning that attachment_id is never a container or work package id, matching the irreversible consequence.

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 ('Permanently delete') and resource ('one attached file from OpenProject'), with the scope narrowed to a single file. It is clearly distinguishable from siblings like delete_work_package or delete_project, and the 'Related' section reinforces the boundary against list/download/upload_attachment.

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 tells the agent when to use it ('only on explicit user instruction') and gives concrete examples (wrong work package upload, superseded document). It names alternatives and their conditions: list_attachments to discover ids, upload_attachment for a replacement, download_attachment to preserve bytes first.

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 destructive annotations, it discloses the cascade of everything destroyed, lack of API-side undo, asynchronous background execution, return shape, admin-rights requirement, and how to verify eventual completion. This is exactly the kind of behavioral context annotations cannot 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?

Despite its length, the description is front-loaded and organized into distinct, useful parts: core action, usage restriction, cascade warning, async behavior, pitfalls, and cross-references. Every paragraph earns its place for a high-risk destructive operation.

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

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

With annotations, a complete input schema, and an output schema, the remaining burden is behavioral and operational clarity. The description supplies the cascade, async caveat, permissions, error meanings, and verification path, making it complete for correct agent use.

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

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

Schema coverage is 100%, and both parameters already have detailed schema descriptions covering confirmation and ID/identifier risks. The tool description reinforces safe usage but does not add parameter mechanics beyond what the schema provides, 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 verb and resource: permanent deletion of a project and everything inside it. It distinguishes this from the reversible archive alternative, `update_project(active=false)`, and from read-only preparation tools such as `get_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?

It gives explicit when-to-use guidance ('Use only on an explicit, specific instruction') and names the safer alternative with its condition. It also points to `get_project` and `list_projects(parent_id=...)` for pre-deletion checks, leaving little ambiguity for an agent choosing among siblings.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the baseline is met; the description goes further by spelling out the downstream effect (hours removed from every cost report and the work package's aggregated spent time) and the absence of any API-side undo. It also discloses the permission requirement and the resulting permission_denied failure, which annotations cannot express.

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

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

Front-loaded with the operative verb and the caution, then grouped into pitfalls and cross-references, which is easy to scan. It loses a point for mild redundancy: the find-the-id and prefer-update guidance appears in both the pitfalls paragraph and the cross-references line.

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

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

For a two-parameter destructive mutation with an output schema and full annotation coverage, the description covers safety, prerequisites, failure modes and alternatives. Nothing an agent needs before calling is missing.

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

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

Schema coverage is 100%, so both parameters including the confirm gate and the id-provenance note are fully documented in the schema. The description never mentions confirm directly and only echoes the list_time_entries id provenance already in the schema, so it adds little beyond the structured fields.

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 ('Permanently delete a logged time entry') with the permanence baked into the first sentence. Cross-references to update_time_entry and list_time_entries make the boundary against siblings explicit.

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

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

Gives an explicit precondition ('only on explicit user instruction, and only for genuinely wrong entries') and names the correct alternative for the common near-miss case (wrong day/duration/activity → update_time_entry). Also states the case where it will fail outright (closed cost-reporting period).

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds substantial context beyond that: work packages survive but lose their version, deletion may be disallowed per instance, 422 when work packages still reference it, 403 means a permission problem, and shared versions affect every project. This is well past the bar set by the annotations.

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

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

Front-loaded with the one-line purpose, then organized into labeled sections (Pitfalls, Cross-references) that an agent can scan. Slightly long, and the sentence about the return value is redundant given an output schema exists, but nothing is wasted in substance.

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

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

For a destructive, non-idempotent mutation, the description covers the safety gate, the failure modes with status codes, the permission requirement, and the blast radius on shared versions. An output schema handles returns, so nothing an agent needs before calling is missing.

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

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

Schema coverage is 100% and both parameters already document themselves, including the confirm=false safety behavior. The description reinforces where to obtain version_id ('list_versions for the id') but adds no syntax or format meaning the schema lacks, so the baseline 3 applies.

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

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

States a specific verb ('Permanently delete') and resource ('a version'), with the permanence qualifier front-loaded. It immediately distinguishes itself from update_version, which the description frames as the normal path for closed releases.

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

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

Gives an explicit inclusion criterion ('only for a version created by mistake') and a named alternative with the exact call signature: ``update_version(status='closed')`` is 'almost always the right answer'. The tradeoff (keeps history, stops new assignments) is spelled out so the choice is unambiguous.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description goes well beyond them: it enumerates exactly what is destroyed (comments, attachments, time entries, relations), states there is no API-side undo, discloses the confirm-gate behavior, and warns that children are not cascaded. That last point is the kind of non-obvious behavior an agent cannot infer from annotations or schema.

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

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

Front-loaded with the core action and the safety gate, then organized into clearly labeled paragraphs (deletion scope, return, pitfalls/alternatives). The only near-waste is the sentence describing the returned confirmation object, which duplicates what the output schema already provides.

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

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

For a destructive two-parameter mutation tool with an output schema, everything an agent needs is present: cascade scope, irreversibility, confirmation requirement, the children caveat, and a recommended safer alternative. Nothing material is left to inference.

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

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

Schema coverage is 100%, so both parameters are already well documented, including the confirm=false failure mode — baseline would be 3. The description adds a small amount of extra framing by tying the child-check to the id argument and reinforcing the irreversibility rationale behind confirm, but it does not introduce new parameter semantics beyond the schema.

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

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

Opens with a specific verb and resource plus the key qualifier ("Permanently delete a work package and everything attached to it"), which is immediately distinguishable from siblings like delete_work_package_relation or delete_project. The scope of the deletion is stated up front rather than buried.

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 gates usage ("Use only on explicit user instruction") and names concrete alternatives with the condition that selects them: update_work_package with a closed status to get the item out of the way, and get_project_metadata to discover which statuses count as closed. It also tells the agent to check for children first via get_work_package, which is a genuine when-to-do-this-before rule.

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

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

Goes well beyond the destructiveHint/no-undo implied by annotations: it warns that deleting a ``follows`` relation drops the scheduling constraint and may reschedule the waiting work package, that a repeat delete returns 404, and that recreating via create_work_package_relation is the only recovery path. These are exactly the side effects an agent cannot infer from structured fields.

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

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

Front-loaded one-line purpose, then labelled "Pitfalls" and "Cross-references" blocks. Every sentence carries a distinct fact (irreversibility, scheduling impact, 404, hierarchy exception) 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?

Output schema exists and the description still notes a small confirmation object is returned; recovery path, failure mode, and the confirm gate (documented in the schema) are all accounted for. Nothing an agent needs to call this destructive tool safely is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description adds behavioral semantics for relation_id (a second delete of the same id returns 404), which the schema does not state. Modest but real added value above 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?

Specific verb (Remove) + resource (the link between two work packages), with an immediate scope clarification that neither work package is touched, only the relation. This cleanly separates it from delete_work_package and from update_work_package_relation.

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 states when to use it ("when a dependency no longer holds") and routes the agent away from adjacent tools: use update_work_package_relation to change rather than remove, use update_work_package(parent_id=null) for hierarchy, and treat missing relations via get_work_package(include=['relations']).

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 explicitly says the bytes are streamed to disk and that a file is written on the server's machine, which is a filesystem side effect. This directly contradicts the annotation readOnlyHint=true, so despite otherwise rich behavioral detail, the contradiction requires a score of 1.

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 definition is front-loaded with the core action and then organized into scoped paragraphs for return values, pitfalls, and related tools. Despite its length, every sentence adds operational value for a download tool with several failure modes.

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

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

An output schema exists, and the description still adds important context: returned fields, SHA-256 verification, progress notifications, size limits, partial-file behavior, and path visibility caveats. It gives an agent everything needed to call the tool correctly, apart from the annotation mismatch noted above.

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 three parameters. The description still adds useful semantics beyond the schema, especially return_image's 1 MB inline-image limit, attachment_id provenance, and target-directory collision behavior.

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

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

The description uses a specific verb and resource: downloading an attachment's bytes to a file. It names how to obtain attachment_id via list_attachments or get_work_package(include=['attachments']), and explicitly distinguishes the operation from upload_attachment.

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

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

It states the prerequisite clearly and places the tool relative to siblings: use list_attachments first, upload_attachment is the reverse direction. It also gives detailed when-not and failure conditions, including quarantined attachments, unfinished virus scans, size limits, and path collisions.

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 substantial context beyond annotations: only comment journal entries are editable, field-change entries are rejected locally before any write, permission requirements produce 403s, the edit replaces all text with no API-visible history, and no notifications are sent. These are exactly the mutation risks an agent needs.

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

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

Front-loaded with purpose, then useful pitfalls and cross-references. It is somewhat long, but nearly every sentence carries operational value; minor redundancy with the schema prevents a 5.

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 write operation with an output schema, permissions concerns, local rejection behavior, and alternatives, the description covers all the key decision and safety information an agent needs 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 description coverage is 100%, so both parameters are already well documented. The description reinforces replacement semantics and activity-id sourcing, but does not add meaning beyond the schema's own 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?

States a precise verb and resource: rewrite the text of an existing work-package comment. It distinguishes the tool from add_work_package_comment, list_work_package_comments, and update_work_package both in the opening line and cross-references.

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 names when to use it (fix typo, correct statement, extend a note) and when not to use it (field-change entries, undo via rewrite, field updates that belong in update_work_package). It also provides the read/add/update alternatives by name.

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

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

With readOnlyHint/idempotentHint already declaring safety, the description adds real behavioral context beyond annotations: it never calls OpenProject, it returns a specific object, it triggers tools/list_changed so the agent must re-read its tool list, and it fails with invalid_input for operator-removed groups. The 'already_visible' status is consistent with idempotentHint.

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

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

Front-loaded with the core action and trigger, then cleanly separated into returns, side effects, and pitfalls. Dense but nearly every clause carries operational information; the group list in both description and schema is mildly redundant.

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, yet the description still names the returned fields and status values, and it covers session scope, side effects, and failure modes. Nothing an agent needs to invoke and recover from this tool is missing.

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

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

Schema coverage is 100% and the schema description already enumerates the accepted group tags and which are hidden under the core profile, including the 'meetings includes recurring' note. The description restates but adds no syntax or selection guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Re-enable a tool group hidden by OPENPROJECT_MCP_PROFILE=core') with scope limited to the session, which no sibling tool covers. An agent can distinguish it from the listing/permission siblings without opening the schema.

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

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

Gives an explicit trigger condition ('when the user needs meetings, wiki, news, documents, budgets, git activity or reporting and those tools are not in your list') plus exclusions (cannot override read-only mode, admin gate, operator-disabled groups). It also cross-references get_instance_info for capability discovery.

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 substantial context beyond annotations: the action itself decides which fields change, the server does not report touched fields, and callers should compare the returned row or re-fetch. It also explains likely 403/422 outcomes, that writes are not auto-retried, and that conflicts return a fresh ``lock_version``.

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?

Despite its length, the description is front-loaded, paragraph-structured, and each section earns its place: purpose, usage, return shape, pitfalls, and cross-references. There is 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 non-idempotent write with an output schema and detailed annotations, the description supplies the operational caveats an agent needs: action availability, server-side conditions, conflict handling, and field-change opacity. Nothing material is missing.

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

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

Schema description coverage is 100%, so the parameter meanings are already fully documented in the schema. The description reinforces that ``custom_action_id`` must come from ``get_work_package`` and that availability is per work package, but does not add much parameter-specific detail beyond the schema.

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

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

States a specific verb and resource: "Run an instance-defined one-click action on a work package." It also distinguishes the tool from siblings by naming ``update_work_package`` as the explicit field-by-field alternative.

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

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

Gives clear when-to-use guidance: use it when ``get_work_package(include=['custom_actions'])`` offers the action rather than reproducing its effects manually. It also names the alternative ``update_work_package`` for cases where the exact fields are known.

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

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

Annotations only cover the read-only/idempotent profile; the description adds far more — that every call actually authenticates instead of answering from cache, what fields come back (attachment ceiling, page sizes, authenticated user, feature probes), and that `features` reflects server version, not the caller's permissions. It even maps failure modes (401 = bad/revoked key, network error = URL/DNS/proxy/TLS) to hints naming the environment variable, which is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the usage trigger, then the return summary, then a labeled 'Pitfalls' block, then sibling routing. Despite its length, each paragraph carries a distinct, non-repeated payload (triggers, outputs, failure meanings, alternatives), so nothing is wasted.

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

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

For a zero-param diagnostic tool with an output schema, this is complete: it covers when to call, what is returned, how to interpret the feature probes, and how to diagnose failures. An agent needs nothing else to invoke it correctly or act on the result.

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?

Zero parameters, so the baseline is 4 and there are no parameter semantics to add. The description does characterize the return payload (instance name, version, feature probes), which is useful but partially redundant given an output schema exists.

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

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

Opens with a specific verb+resource: checks the OpenProject connection and reports what the instance supports. It explicitly delineates scope against siblings by routing per-project metadata to `get_project_metadata` and user capabilities to `list_permissions`, so an agent can place it precisely in the tool set.

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

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

Gives explicit triggers: call first on unexplained failures, when the user asks 'am I connected / who am I', and before using a version-gated parameter. It also names the alternatives for adjacent needs, which covers the when-not cases by redirection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, but the description adds substantial beyond-schema context: 200 does not guarantee success, status values and null semantics, polling expectations, stale-job 404 ambiguity, and the absence of a retry API. These are exactly the behavioral traits 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?

The opening sentence states the purpose, then separate 'Returns', 'Pitfalls', and 'Cross-references' sections organize the necessary detail. Despite being longer than average, every sentence earns its place for an asynchronous status tool.

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

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

The tool has an output schema, but the description still covers terminal states, null semantics for successful, result_url/project on finished copies, stale 404 handling, and failure reporting. Nothing material is missing for correct invocation and interpretation.

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

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

Schema description coverage is 100%, and the schema already explains that job_id is a uuid from copy_project or delete_project, never a project id. The description reinforces the origin of the id but does not add parameter format or validation details beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('check whether a background job... has finished') and immediately distinguishes the tool from siblings by tying it to copy_project/delete_project job ids. The agent can tell this is the status-checking tool rather than a project or work-package operation.

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

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

Explicitly says to call it after copy_project or delete_project and wait for a terminal state. It also names alternatives for verification (get_project/list_projects) when a 404 occurs, and describes polling behavior rather than leaving it inferred.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substance beyond them: rich text is returned as markdown with html dropped, an empty status_code means no status rather than 'on track', and a 404 means a bad id or an archived/invisible project with an error hint. Those are exactly the behavioral traps an agent would otherwise hit at runtime.

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

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

Well front-loaded: purpose first, then usage, then return shape, then pitfalls, then alternatives. Most sentences earn their place, though the explicit return-field list is somewhat redundant given an output schema exists, and the parenthetical enumerations add bulk.

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 purpose, trigger conditions, failure mode (404 with hint), field semantics (status_code), and next-step tools, which is more than enough for a single-parameter read tool. Redundancy with the output schema on the return field list is the only, and harmless, excess.

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

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

Schema description coverage is 100% and the parameter doc already explains the integer-id vs. slug-identifier duality, so the description mostly repeats it. It does add a diagnostic angle by tying a 404 to a wrong id/identifier spelling, but it offers no new syntax or format detail beyond the schema, making baseline 3 correct.

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 ('Read one project in full') and explicitly contrasts with the sibling list_projects by saying to use it *after* listing. The enumerated return fields further pin down what 'full' means, so an agent can distinguish it from list_projects, update_project, or get_project_metadata 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 a concrete trigger ('after list_projects when you need the description, the status explanation or the parent') plus a second use case (resolving an id/identifier a user supplied). It also routes to the correct alternatives: get_project_metadata for ids valid inside the project and list_work_packages for work packages, so the agent knows when not to use this tool.

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

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

Beyond the readOnly/idempotent annotations, it discloses the 300 s cache and the refresh escape hatch, the conditional shape of the result depending on project_id, the per-row flag semantics (is_closed as the authoritative done marker, is_milestone, is_default), and the non-obvious failure mode where a missing module or permission yields an empty list with a note rather than an error. That last point is exactly the kind of silent-success caveat annotations cannot carry.

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

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

Front-loaded with the purpose and the call-now instruction, then payload shape, then pitfalls, then sibling routing — a sensible order with no filler sentences. It loses a point for restating the project_id conditional that the schema description already covers, which is the one block that does not fully earn its space.

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 everything an agent needs before invoking a zero-required-parameter metadata lookup: when to call it, what the payload differs by, how to read the flags, staleness, and the silent-empty failure mode. With an output schema present the description needn't enumerate returns, so its extra detail is bonus rather than padding.

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 earns an extra point by spelling out the conditional payload for each parameter value (global sets when project_id is omitted, project-scoped narrowing plus versions/categories/activities when supplied) and by warning that priority and activity ids differ per instance. It does not add format or syntax detail beyond the schema.

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

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

The opening sentence states a specific verb and resource (list ids/names valid on this instance) and is reinforced by the concrete question it answers ("what do I pass for type / status / priority / version / category / activity"). It explicitly distinguishes itself from the two nearest siblings, get_work_package_schema and list_projects, so an agent can route correctly without opening a schema.

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

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

Gives explicit when-to-use triggers: before any create or update, before filtering by ids, and on allowed-values write errors. It also states the exclusion boundary — that this tool does not return writable/custom field schemas (use get_work_package_schema) and does not return project ids (use 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 declare readOnly/idempotent/non-destructive, and the description still adds substantive context: no phases index exists, phase dates are unexposed by the API, and a 404 conflates wrong id, missing permission (view_project_phases), and pre-16.1 instances. That is real behavioral disclosure beyond the structured data.

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

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

Front-loaded with purpose, then usage, return shape, pitfalls, cross-references. Well organized with zero filler prose, though the explicit return-field list is somewhat redundant given an output schema exists.

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 single parameter, an output schema, and rich annotations, the remaining risks (where ids come from, what a 404 means, which sibling answers date-based questions) are all covered. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the schema already says it is a per-project phase record id from a work package reference, not a definition id. The description reinforces the sourcing constraint ('ids only come from work packages' project_phase references'), adding marginal value beyond the schema rather than new syntax detail.

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

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

States a specific verb and resource ('Read one project's phase record') plus the exact returned fields, and explicitly separates itself from list_project_phase_definitions in Cross-references. An agent can distinguish it from the catalog-listing sibling without opening either schema.

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

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

Gives an explicit trigger ('after get_work_package surfaced a project_phase reference'), names the alternative for the adjacent question ('which projects are in this phase now' goes through list_projects(in_phase=...)'), and explains the 404 conditions. When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: the response is the list shape plus created_at/updated_at, and sprint ids live in a different id space than version ids. It stops short of saying what happens on a bad or foreign id, but the added behavioral detail is meaningful.

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

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

Front-loaded with purpose, then usage, pitfalls, and cross-references in clearly labeled chunks. Every sentence carries information; nothing is redundant.

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 still covers when to call it, what it adds over the list endpoint, the id-space hazard, and follow-on tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by warning that a version id from list_versions will not resolve here, which is semantic guidance the schema's 'Numeric sprint id from list_sprints' only hints at.

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 ('Read one sprint in full') plus the returned facets (dates, workspace, lifecycle status), which lets an agent separate it from list_sprints without opening either schema.

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

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

Explicitly says to use it only after list_sprints has supplied an id and the list row is insufficient, and names cross-references (list_sprints for the id, list_work_packages with sprint_ids for contents). Both the when and the boundaries are stated.

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

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

Goes well beyond the annotations (which only cover read-only/idempotent/no-destroy) by disclosing visibility-dependent field behavior — a null means 'not visible', never 'empty' — that `admin=true` does not imply project permissions, and that group or placeholder ids return 404. These are exactly the traps an agent would otherwise hit.

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

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

Purpose and return shape are front-loaded, followed by usage, then a clearly labeled 'Pitfalls' block and cross-references. Every paragraph carries distinct information, including the justification for the deliberately omitted avatar URL, so nothing reads as 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?

Although an output schema exists, the description still previews the return payload and explains the notable omission, then covers the failure mode (404) and permission caveats. For a one-parameter read tool, an agent has everything needed to call it correctly and interpret nulls.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, so the baseline is 3. The description adds practical value by explaining the `'me'` sentinel's purpose (learning which account the server authenticates as) and reinforcing that group/placeholder ids are rejected, beyond the schema's wording.

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 ('Read one user's profile') and enumerates exactly what is returned (name, login, email, admin, status). It is clearly distinguished from the similarly named `search_principals`, which the description explicitly frames as the id-lookup step that precedes this call.

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?

Names the precise trigger ('after search_principals when you need more than a name') and gives three concrete scenarios: confirming an account is active before assigning work, checking instance-admin status, and discovering the acting account via `id_or_me='me'`. It also routes the agent elsewhere for adjacent questions (`list_permissions` for actual capabilities, `list_memberships` for roles).

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds substantial non-obvious behavior: lock_version is required for safe concurrent updates, includes are capped at 20 with more_via reporting, and a 403/404 sub-resource degrades into a notes entry rather than failing the read. These are exactly the traits an agent could not infer from structured fields.

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

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

Front-loads the core action, then usage, then return shape, then pitfalls, ending with sibling routing. Despite its length, each sentence carries distinct operational information; nothing is padding.

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

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

For a read tool with a rich output schema and full annotation coverage, nothing an agent needs to invoke it correctly is missing — parameter limits, failure degradation, follow-up tools, and the update handoff are all present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it — the per-include 20-item cap, the truncation signal, and the cost model ('every include is one more upstream request'). The id semantics (semantic 'PROJ-42' form) are already in the schema, so no extra credit there.

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

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

Opens with a specific verb+resource plus scope: 'Read one work package in full: description, dates, custom fields, parent and progress.' It explicitly separates itself from list/search siblings and notes it is the only way to read description text, which is not obvious from the name alone.

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

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

States the entry condition precisely ('once a search or list has given you an id') and routes three adjacent needs to their dedicated tools: list_work_package_comments for threads, download_attachment for bytes, get_work_package_git_activity for PRs/commits. Also names the recovery path (list_work_packages(parent_id=…)) when children truncate.

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 non-obvious behavior: writable:false fields are computed and sending them is an error rather than a no-op, allowed_values is null when the API only gives a lookup URL, and long option lists are capped at 50 with a note. These are exactly the failure modes an agent would otherwise hit.

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

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

Front-loaded with purpose and trigger, then returns, then pitfalls — a good shape. The explicit enumeration of return fields is somewhat redundant with the existing output schema and pads length, but no sentence is filler.

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

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

For a read-only schema-introspection tool with full schema coverage, rich annotations and an output schema, this covers everything: when to call it, what it returns, what the keys mean on the wire, and which sibling to use when a value cannot be resolved here.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds provenance — both ids come from get_project_metadata — and reinforces that the schema is per project AND type. It does not, however, explain the refresh/cache parameter, which is left entirely to the schema.

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

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

States a specific verb and resource plus scope: 'Show which fields a work package of this type accepts in this project.' It is immediately distinguishable from get_work_package (which reads values) and from create/update_work_package, which it explicitly precedes.

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 concrete triggers: before create/update when you need required fields, when you want a custom field key or its allowed options, or after a 422 naming an unknown field. It also names the alternatives for cases this tool does not cover — get_work_package for actual values, search_principals/list_projects for lookup-URL fields, get_project_metadata for ids.

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 already covering read-only, idempotent and non-destructive, the description goes further: it discloses that the upstream collection is unpaginated so has_more is always false and total equals row count. It also explains the virus-scan status vocabulary and which values are downloadable, plus what a 404 means.

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

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

Front-loaded with purpose, then return shape, then pitfalls, then related tools — a sensible order with no filler sentences. It is on the long side and repeats a little of the schema's comment/activity-id note, which keeps it from a 5.

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 filtered-list tool it covers calling context (enabled modules, forum-post gap), return semantics (envelope, row fields, status meanings) and adjacent tools. Even though an output schema exists, the extra explanations fill in the gaps an agent would otherwise have to discover at runtime.

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 already 100%, and the description still adds value by emphasizing that container_id is the container and never an attachment id, and by listing which modules (meetings, budgets, documents) can cause a 404. Some of the comment/activity-id guidance duplicates the schema, so it is a notch below fully additive.

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

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

States a specific verb and resource ('List the files attached to one container') and immediately enumerates what a container is. It also contrasts itself with siblings (download_attachment, upload_attachment, get_work_package(include=['attachments'])), so an agent can place it precisely in the tool family.

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

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

Gives explicit when-to-use: discover attachment ids before calling download_attachment, or check what a work package already carries. The Related section names alternatives and what each does differently, leaving little to inference.

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

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

Annotations only declare a safe read; the description adds substantial non-obvious behavior: 404/403 conditions still return a 200 with an EMPTY list plus a note, empty is never proof of no documents, permission values ('View allowed', 'Not found', null) determine whether URLs work, and returned URLs require the user's own OpenProject login since the server cannot fetch bytes. None of this is inferable from structured fields.

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

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

Front-loaded with purpose, then the attachments pairing, pitfalls, and related tools in a logical order; the pitfall paragraph is dense but earns its place. It runs longer than needed, and the pitfall about 403/empty lists is stated twice in slightly different words.

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

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

Covers prerequisites (storages module, storage connected to project), failure modes, permission semantics and the envelope (has_more always false). Some redundancy with the output schema when enumerating row fields (file_name, mime_type, origin_id), but that enumeration supports the URL caveat, so the detail is justified rather than missing.

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

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

Schema coverage is 100% and the single parameter's description already specifies provenance ('from search_work_packages, list_work_packages or get_work_package — never an attachment id and never a project id'). The prose adds no further guidance on work_package_id, so the schema carries the load.

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

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

States a specific verb and resource ('List the external-storage files ... linked to a work package') and immediately disambiguates the concept from attachments: 'instead of living inside OpenProject like an attachment, the document stays in a connected storage.' An agent can distinguish list_file_links from list_attachments without opening either schema.

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

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

Explicitly says to pair with list_attachments because 'the two lists are disjoint and neither implies the other', and names out-of-scope operations (creating/deleting links, browsing remote storage) with a redirect to the UI. It also names the wrong tool to use for bytes (download_attachment does not work here).

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral context: the return envelope shape, the pitfall that row `id` is a membership id (mixing it up revokes the wrong access), that group memberships can mask access, and that admin tools are gated behind an env flag.

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

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

Front-loaded purpose sentence, then usage, return shape, pitfalls, and cross-references in clearly labeled blocks. Every section is useful, though the return-envelope paragraph is somewhat long given an output schema exists.

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 everything an agent needs: when to call, what comes back, the id-confusion trap, the group-membership blind spot, and the role-vs-permission distinction. A mutation-adjacent read tool with this much nuance is fully described.

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

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

Schema coverage is 100% and each parameter already documents its id semantics and cross-references search_principals. The description's 'filter' advice and the project_id+principal_id combination are already present in the schema, so it adds little beyond 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?

States a specific verb and resource ('List who has access to which project, and with which roles') and immediately clarifies the scope (membership, not permissions). It is clearly distinguishable from sibling read tools like list_projects or list_roles.

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?

Explicit when-to-use cases are given (pre-grant/revoke checks, auditing, reachability), plus a warning that an unfiltered call pages through everything and should be filtered. Alternatives are named for role ids, principal ids, and mutations.