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

Annotations already declare non-readOnly, non-destructive, non-idempotent, open-world, so the safety profile is covered. The description then adds genuinely non-obvious behavior: OpenProject may aggregate a new comment into an existing journal entry, `details`/`created_at` are omitted unconditionally, `details_omitted` is true, and `user` may be null after a failed follow-up lookup. It stops short of explaining permissions or the preview/confirm write flow.

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

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

The purpose is front-loaded and correct, but the aggregation explanation is a single sprawling multi-clause sentence that reasons through 'no reliable way to tell an aggregated response from a fresh one' at length. The same fact – details/timestamp are always omitted because of journal aggregation – could be stated in a quarter of the text.

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

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

With no output schema, the description carries the return-value burden and does so for the tricky parts (omitted fields, `details_omitted`, possibly-null `user`). The remaining gap is that it never says what a successful response otherwise contains and says nothing about `internal` visibility semantics for a mutation tool.

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

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

Schema coverage is 40%, so the description should compensate. It clarifies `notify` beyond the bare 'Notify' title, and the schema itself documents `work_package_id` and `confirm`. However, `internal` (internal vs. external visibility) is undocumented in both places and `comment` gets no guidance.

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: 'Add a comment to a work package.' Unambiguous, and no sibling tool competes for this action. It does not explicitly differentiate itself from siblings, but the operation is inherently distinct.

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

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

The only usage-adjacent statement is 'notify=false avoids change emails by default,' which is a parameter default rather than when-to-use guidance. Nothing is said about when to prefer an internal comment, when to use this versus editing the work package description, or when the confirm/preview flow matters.

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 the annotations (destructiveHint=true, idempotentHint=false) by disclosing that the operation is non-atomic, that per-item validation failures are not tool errors, that a per-item timeout does not stop the loop, that an outright cancellation leaves already-created items on the server with no result summary, and that due_date may be silently shifted off non-working days with no opt-out. This is exactly the mutation-risk context an agent needs and 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?

Front-loaded with the core action and organized into topical paragraphs (fields, errors, select, cancellation, ordering), so it scans well despite its length. The field enumeration is long but each item carries non-obvious semantics; a few clauses (e.g. restating that listing always-included fields in select changes nothing) could be trimmed.

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

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

There is no output schema, yet the description fully explains the per-item result shape (index, success, error, nested result), how items map back to inputs, and what to do after a cancellation (query list_work_packages/get_work_package). Combined with the partial-failure and size-limit guidance, an agent has everything needed to call this correctly and interpret the outcome.

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

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

With only 67% schema coverage, the description compensates thoroughly: it names the three required keys, enumerates every optional field with semantics the schema lacks (target_versions is incompatible with version, parent is an alias for parent_work_package_id and must not be combined, ISO8601 duration format, YYYY-MM-DD dates), and warns that unknown keys are rejected rather than dropped. It also explains select precisely (write-result fields vs. the nested result work package, index/success/error always included) and what confirm=false vs. true does.

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+scope ('Create multiple work packages in one call') and immediately differentiates itself from bulk_update_work_packages by noting there is no identifier field, only an index-based match. It also contrasts itself with create_work_package/create_subtask, so an agent can pick it out of a very crowded sibling list 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 selection rule against alternatives: use this instead of parallel create_work_package/create_subtask calls when the relative order of a batch matters. It also prescribes when to set select proactively (many items or long descriptions) and requires user approval of the preview before setting confirm=true.

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 (destructive/idempotent/openWorld) with real behavioral detail: unknown keys are rejected with indexed errors, 'none' clears nullable fields, closed status auto-fills percentage_done/remaining_time, and percentage_done plus a closing status is hard-rejected on status-based-progress instances. However, the confirm/preview contract, item-trimming via select, and cancellation/atomicity semantics — critical for a destructive tool — are delegated to bulk_create_work_packages rather than restated.

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 highest-value fact (the work_package_id key naming) and is organized as lead sentence, field inventory, then edge-case rules. It is dense and the target_versions/sprint parentheticals plus the deferred-contract paragraph make it longer than strictly necessary, but every sentence carries operational rules.

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

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

No output schema exists, and the description partially compensates by naming result shape fields (result.result.due_date, work_package_id, ready, state, display_id) and noting that select refers to write-result fields. Combined with the schema's confirm parameter documenting preview vs. execute, the description is nearly complete, though atomicity/cancellation behavior must still be read from a sibling.

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?

Adds substantial meaning beyond the 67%-covered schema: the 'none' sentinel for clearing, mutual exclusion of target_versions vs version and parent vs parent_work_package_id, target_versions [] to clear all, ISO8601 duration format, YYYY-MM-DD dates, percentage_done 0-100, and that select names write-result fields rather than work package fields. This compensates for the schema's terse titles.

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+scope: 'Update multiple work packages in one call'. The bulk scope distinguishes it from update_work_package, and the explicit instruction that the key is `work_package_id`, not `id`, immediately separates it from the single-item sibling's payload shape.

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

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

Usage context is clear from 'in one call' and the repeated comparison to update_work_package ('same as update_work_package', 'matching update_work_package's naming') plus the pointer to bulk_create_work_packages for shared contracts. It never states an explicit when-not-to-use (e.g. use update_work_package for a single item), leaving that inference to the agent.

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

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

Annotations declare destructive/idempotent, but the description adds what actually happens underneath: a cancelled Meeting record is created, its id is not returned, and a series schedule change (other than time of day) can delete it later. It also names the recovery path (list_meetings / list_recurring_meeting_occurrences filter='cancelled'), 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 core action, then a version requirement, then parameter guidance, then the materialized-vs-virtual branch. Dense and nearly waste-free, though the informal parentheticals and line-broken layout make it slightly harder to scan than a tight paragraph would.

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?

No output schema, so the description correctly notes that the result omits the new meeting's id and tells the agent how to locate it afterwards. Version requirement, failure mode, recovery path and semantics are all covered for a destructive mutation.

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

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

Schema coverage is 67%; start_time is undocumented in the schema, and the description compensates by specifying ISO 8601 and tying it to init_recurring_meeting_occurrence's addressing scheme. The confirm preview/apply workflow is left to the schema rather than reinforced here, so this stops short of 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 ('Cancel a ... recurring-meeting occurrence') with the crucial qualifier 'virtual (not-yet-materialized)', which distinguishes it from delete_meeting and init_recurring_meeting_occurrence. An agent can immediately tell what this does and what it is not.

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

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

Explicitly routes the agent: if the occurrence is already materialized, use delete_meeting on the real Meeting instead; if not, this tool records a cancelled Meeting that init_recurring_meeting_occurrence can restore. Names the alternatives and the exact conditions selecting them.

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 annotations, it discloses the asynchronous background-job behavior, the need to poll get_job_status with job_status_id, and that rejected validation previews are not MCP errors but should be inspected via ready and validation_errors. These are high-value, non-obvious behavioral details.

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

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

The description is short and front-loaded: purpose first, then parameter scoping, then async job behavior, then validation-error handling. Every sentence carries necessary 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?

Given a 10-parameter mutation tool with no output schema, the description covers the critical operational details: preview versus confirmed execution, background polling, and validation results. An agent has enough context 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 parameter documentation is already strong. The description adds useful grouping by saying name, identifier, and optional fields describe the new project, but it largely reiterates schema-level confirm semantics rather than adding substantially new parameter guidance.

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: copy an existing project into a new project. It is clear and distinguishable from generic create/update siblings, though it does not explicitly name those alternatives.

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

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

It explains the confirm-preview workflow and says to poll get_job_status after a confirmed copy. It does not explicitly contrast with create_project or list when copying is preferable, but the operating context is clear.

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

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

Annotations declare a non-read-only, non-destructive, non-idempotent, open-world write; the description adds meaningful context by clarifying that what is persisted is a query definition (filters, columns, sorting, grouping) rather than a grid layout. It does not surface the preview/confirm two-step or the fact that some inputs are ignored, but the schema documents both, so the gap is modest.

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

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

Two sentences, zero filler, with the core definition front-loaded and the sibling disambiguation second. The line break is cosmetic and does not hurt readability.

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 14-parameter mutation with no output schema, the description covers identity and routing, and the schema carries the rest. What is missing is the workflow-level context an agent needs before calling it: the preview-then-confirm approval loop and the permission implications of `public`.

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 every one of the 14 parameters is already documented in detail, including the ignored `hidden` flag and the confirm-preview semantics. The description only names the query attributes generically (filters, columns, sorting, grouping), which adds little beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ("Create a saved OpenProject board/query") and immediately defines what the resource actually is: a persisted work package query with filters, columns, sorting and grouping. It also explicitly separates itself from the sibling create_grid, so an agent can route correctly 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 alternative: if the intent is a board grid showing queries as columns, use create_grid instead. That is a real routing decision the agent would otherwise get wrong. It stops short of full when/when-not coverage (e.g. no mention of update_board for existing boards or permissions for public boards).

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 is a non-read-only, non-destructive, open-world, non-idempotent mutation, so safety signaling is carried by structured fields. The description adds useful behavior (grid is seeded with default widgets, widgets are managed elsewhere) but does not cover permissions, the preview-then-confirm flow, or what gets created/returned, which the schema partly handles.

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

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

Front-loads the action in one short sentence, then adds only two supporting sentences of genuinely useful context about default widgets and create_board. No redundant restatement of name or schema fields.

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 create tool with no output schema but a fully documented input schema (including the confirm preview), the description supplies enough conceptual context to call it correctly. It could say slightly more about what a successful creation yields or permission needs, but the essentials are 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 every parameter including the confirm preview semantics and scope path rules is already documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States the specific verb (create) and resource (dashboard grid) plus where it lives (a page), and defines what a grid is: the widget layout of My Page, a project overview, or a board. It also names the sibling create_board and explains that a board's saved queries come from it, so the agent can distinguish the two without opening schemas.

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

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

Explicitly notes that the grid starts with OpenProject's default widgets and that other widgets are added in OpenProject rather than via this tool, and routes board query creation to create_board. Clear context, though it doesn't explicitly contrast with update_grid or list_grids or state prerequisites.

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 mutability (non-read-only, non-destructive, not idempotent), and the description adds real behavioral context: the meeting is created as a draft with notifications off, and state/notify are rejected. It does not mention permission requirements or what the response contains, which keeps it below a 5.

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

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

Front-loaded with the operation and version, then two short field-specific notes. Every sentence carries new information and 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 10-parameter creation tool with no output schema, the description says nothing about what is returned (e.g., the new meeting id), which an agent needs to chain follow-up calls. Behavioral and parameter context is otherwise adequate for the tool's complexity.

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

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

With only 30% schema description coverage, the description compensates by explaining the duration format (ISO 8601, hours/minutes only) and the rejection of state/notify. Combined with the schema-documented confirm and participant_user_refs, the important semantics are covered, though sharing, location, and start_time receive no added meaning.

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

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

States a specific verb and resource ("Create an OpenProject meeting") with a version prerequisite. It does not distinguish itself from siblings like create_recurring_meeting, but the intended operation is unambiguous.

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

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

It gives explicit constraints (requires 17.4+) and pre-empts a common misuse by saying state and notify cannot be set on create and should be set with update_meeting instead. No general when-not-to-use guidance, but the routing for the excluded fields is clear.

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

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

Adds real context beyond annotations: version gating, the closed-meeting rejection rule, and the OPENPROJECT_WRITE_PROJECTS write guard, which annotations alone (readOnlyHint=false, destructiveHint=false) do not convey. It stops short of warning that the call is non-idempotent, i.e. repeating it creates duplicate items, which is the one behavior an agent most needs to know.

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

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

Three front-loaded sentences: purpose first, then the key precondition, then the routing rule to the alternative tool. No filler and no repetition of schema text.

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 an 8-parameter mutation with no output schema, the description covers preconditions, permissions, and sibling routing well, while confirm/preview semantics and id defaults are covered by the rich schema. Minor gap: nothing about ordering or duplicate creation.

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 a cross-parameter constraint the schema cannot express: a work_package item's project must fall inside OPENPROJECT_WRITE_PROJECTS. It does not otherwise elaborate on parameters such as confirm, which the schema already documents well.

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 ('Add an item to a meeting's agenda') and explicitly names the sibling it is not for ('To record a result of a discussed item use create_meeting_outcome'), so an agent can pick it apart from the outcome tools without opening schemas.

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

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

Gives when-to-use, when-not ('Rejected while the meeting is closed'), prerequisites (OpenProject 17.6+, project inside OPENPROJECT_WRITE_PROJECTS) and the alternative tool for the adjacent use case. Nothing essential 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?

Beyond the annotations (readOnly=false, destructive=false, idempotent=false), it discloses the version requirement and, notably, that a wrong kind value triggers a 500 internal server error instead of a clean validation error — genuinely useful behavioral context for an agent. It does not describe the write result or whether duplicates are allowed, but the safety profile is already carried by 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?

Purpose is front-loaded in the first sentence, then constraints follow in a sensible order. The parenthetical warning about "info"/"action" is long but earns its place by preventing a server error; the prose is otherwise tight.

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

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

A mutation tool with 5 parameters and no output schema; the description covers purpose, version gate, enum values, and per-kind requirements, while the confirm preview workflow is documented in the schema. Only the return shape (does it return the created outcome?) is left unstated, a minor gap.

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

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

Schema coverage is only 40% and the kind parameter has no enum in the schema at all, yet the description enumerates the exact valid values and explicitly rejects near-miss strings like "info" and "action". It also states the conditional requirements linking kind to notes and work_package_id, which the schema does not express.

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?

"Create a meeting outcome on an agenda item" gives a specific verb (create), a specific resource (meeting outcome) and its parent scope (agenda item), which separates it cleanly from create_meeting, create_meeting_agenda_item, and update_meeting_outcome in the sibling list.

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

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

The description gives real preconditions: the OpenProject 17.6+ version floor, the allowed kind values, and which parameters each kind forces (notes for information, work_package_id for work_package). It does not say when to prefer this over update_meeting_outcome or how it relates to an existing outcome, so it stops short of full alternative routing.

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

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

Annotations already declare the mutation safety profile. The description adds meaningful behavioral context by requiring OpenProject 17.6+ and warning that backlog is immutable after creation, which is not captured by annotations. It does not explain the confirm-preview workflow, though the schema does describe confirm separately.

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 very short and front-loaded: the action comes first, followed by the version requirement and the backlog constraint. Every sentence adds practical information 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?

For a mutation tool with five parameters and low schema coverage, the description covers the most non-obvious constraint but does not provide enough parameter or workflow context. Annotations reduce the safety-disclosure burden, but the low schema coverage still leaves gaps around required fields and positioning.

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 only 20%, so the description needs to compensate for undocumented parameters. It adds useful semantics for backlog, but leaves title, meeting_id, and position unexplained, and only marginally clarifies the creation flow.

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: 'Create a meeting section.' It is distinguishable from update_meeting_section and delete_meeting_section by the create action, but it does not explicitly compare itself to those siblings.

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

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

It gives a version prerequisite and a useful create-only rule for the backlog field. However, it does not explicitly say when to create a new section versus updating an existing one, nor does it describe workflow expectations for positioning or confirming creation.

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 disclose that this is a non-read-only, non-destructive, non-idempotent mutation. The description adds useful behavioral context beyond annotations by explaining that the preview is validated by OpenProject and that problems are returned in validation_errors. It does not contradict the annotations.

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

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

The description is two short sentences, front-loads the core action, and contains no wasted wording. Both sentences contribute useful 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 schema and annotations are rich enough to support calling the tool, but there is no output schema. The description notes validation_errors but does not explain the successful return value or summarize the confirm/apply workflow, leaving some contextual gaps for a mutation tool.

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

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

Schema description coverage is 100%, so all five parameters are already well documented in the input schema. The description does not add parameter-specific meaning beyond that, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Create a project membership.' This clearly distinguishes it from update_membership and delete_membership by operation type, though it does not explicitly name or route the agent away from those siblings.

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

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

The description does not say when to use create_membership versus update_membership, when not to use it, or what prerequisites are needed. The mention of preview validation hints at the tool's workflow but does not provide explicit usage guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the project-scoping context and says nothing about the two-phase confirm/preview behavior, permission requirements, or whether duplicate titles are allowed — meaningful traits for a mutation tool.

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

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

A single front-loaded sentence with zero waste, but it is under-specified rather than efficient — the brevity leaves real gaps (confirm workflow, permissions) that would have earned their place.

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

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

With 5 parameters, full schema coverage, and mutation annotations, the essentials are covered by structured fields; however, no output schema exists and the description never says what a successful create returns (e.g. the new news id) or how the confirm preview behaves, leaving gaps an agent would want filled.

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 title length, summary length, Markdown description, flexible project identifier, and the confirm preview/apply semantics are all documented in the schema. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ('Create a news entry') and scopes it to 'inside a project', which is enough for an agent to distinguish it from get_news/list_news. It does not contrast itself with update_news or explain why one would create news versus other project content, so it falls short of full sibling differentiation.

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

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

The description offers no when-to-use guidance, no prerequisites (e.g. project membership/permissions), and no mention of the preview-then-apply workflow that the confirm parameter implies. An agent must infer usage entirely from the schema.

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

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

Adds real context beyond the annotations: omitted optional fields are not sent so OpenProject defaults apply, and the two-phase preview/apply pattern is disclosed. It also explains that a rejected preview returns in `ready`/`validation_errors` rather than the MCP error envelope, which is genuinely non-obvious. It stops short of stating permission requirements or the fact that confirm=true is a real, non-idempotent write.

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

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

Four short sentences with no padding, and the result-inspection caveat is placed after the default-behavior note. Slightly back-loaded: the most actionable detail (preview vs apply) could have been front-loaded above the defaults sentence.

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 9-parameter mutation with no output schema, the description covers the two things an agent would otherwise get wrong: the confirm gate and where validation failures appear. Missing only permission/authorization notes and what a successful result contains.

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 per-parameter meaning (including `confirm` and `status`) is already fully documented. The description only adds the general rule that omitted optionals fall back to defaults, which is marginal added value; 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 ('Create a project') which unambiguously distinguishes it from update_project, copy_project and delete_project in the sibling list. However it adds no scoping detail (where the project lands, required identifier constraints) that would sharpen purpose beyond the name itself.

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

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

Implies the create flow and explains the confirm/preview protocol, but never says when to use this versus copy_project or when a project should be created at all. No prerequisites (permissions, uniqueness of identifier) are given.

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

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

Annotations declare non-read-only, non-destructive, non-idempotent, open-world; the description adds real behavioral context beyond them — the template meeting is created as a draft, and occurrences do not exist until initialized. It does not cover the preview/confirm workflow or authentication needs, but the confirm preview semantics are already spelled out in the schema, so the remaining gap is minor.

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

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

Three short sentences, front-loaded with the action and the object, then the sibling routing, then the occurrence lifecycle. Nothing is wasted and the line breaks do not impede reading.

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

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

For a 12-parameter scheduling tool with no output schema, the description covers version requirements, sibling alternatives, draft state, and occurrence lifecycle. The only real omission is what the call returns (e.g. the series identifier an agent would need for follow-up calls), which the schema cannot supply.

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

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

Schema description coverage is 100%, so all twelve parameters including the frequency/end_after conditional dependencies are already documented. The description adds no parameter-level meaning beyond the schema (no frequency/interval interaction guidance), so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a recurring meeting series') and immediately distinguishes the artifact from a single meeting and from the series' individual occurrences. An agent can tell this apart from create_meeting, update_recurring_meeting, and init_recurring_meeting_occurrence 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?

Explicitly routes the agent: 'For a single meeting use create_meeting' and 'the series is changed with update_recurring_meeting', plus the prerequisite 'Requires OpenProject 17.4+'. It also flags that occurrences are virtual until init_recurring_meeting_occurrence creates one, which is the key alternative an agent would otherwise get wrong.

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 a destructive, non-idempotent, open-world write, so the bar is lower; the description still adds real behavior beyond them — payload validation before writing, the non-deterministic ID ordering under concurrency, and the mutually exclusive version fields. It omits the preview/confirm workflow (only documented in the confirm parameter) and says nothing about permissions or what a validation failure looks like.

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

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

Purpose is front-loaded in the first sentence and each following sentence adds a distinct constraint (validation, ordering, version exclusivity) with no filler. The mid-sentence line breaks make it slightly harder to scan, but 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?

For a 15-parameter mutation with no output schema, the description covers the tricky interactions but leaves the agent without guidance on the preview-then-confirm flow at the top level, on which of the many optional fields are typically required, or on failure behavior. Adequate but clearly incomplete for this schema size.

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

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

With 15 parameters and only 13% schema description coverage, the description must compensate and largely does not. It explains target_versions (multi-version assignment) and its exclusivity with version, but the other thirteen parameters — type, subject, assignee, category, priority, dates, responsible, custom_fields, project_phase, confirm — get no semantics at all.

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 subtask') and pins it to a required parent ('under an existing work package'), which distinguishes it from the generic create_work_package sibling. It does not explicitly say 'use create_work_package for top-level items', so the sibling boundary is implied by the parent requirement rather than spelled out.

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 routing guidance: use bulk_create_work_packages when ordering across several new items matters, and target_versions vs version cannot be combined. It does not state prerequisites such as required permissions or when a subtask should be created versus a child work package via create_work_package.

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 carry the write/open-world/non-idempotent profile, and the description adds real behavioral facts beyond them: start_time is silently ignored unless an instance setting is enabled, and end_time is server-derived (read-only) rather than settable. It doesn't discuss side effects on work-package spent time or duplicate-entry behavior, but the key silent-failure mode is disclosed.

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

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

Four short paragraphs with the purpose front-loaded and each following sentence introducing a distinct, non-obvious fact (duration format, conditional start_time, derived end_time, sibling routing). No filler or repetition of the schema.

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

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

For a 10-parameter mutation with no output schema and 30% coverage, the description covers the trickiest inputs but omits what 'activity' should be (a sibling list_time_entry_activities exists and isn't referenced), what 'spent_on' expects format-wise, and what 'ongoing' toggles. The confirm/preview workflow is handled by the schema, so its absence here is acceptable, but the remaining gaps are material.

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

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

With only 30% schema coverage, the description does the heavy lifting on the two hardest parameters: hours is an ISO8601 duration with 'PT8H'/'P1D' examples, and start_time is an ISO 8601 date-time with an enablement condition. It also explains why no end_time exists. Activity, spent_on, ongoing, and user remain undocumented in both places, so it doesn't fully compensate for the coverage gap.

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

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

The opening sentence names a specific verb and resource ('Create a time entry') and the closing sentence differentiates it from the sibling create_time_entry_until by the exact condition that separates them (end time vs. hours). An agent can pick between the two creation tools from the description 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?

It gives an explicit alternative and the condition selecting it ('Use create_time_entry_until to specify an end time instead of hours directly'), plus a runtime prerequisite for start_time ('requires the instance setting "allow tracking of start and end times"; ignored otherwise'). It stops short of stating when not to log time at all or noting the sibling that supplies valid activity values.

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 mutating, non-idempotent, non-destructive behavior, and the description adds genuinely new context: hours are computed locally and only hours + start_time are submitted because the server rejects end_time, plus the strict end_time > start_time constraint. It stops short of stating permission requirements or what the confirm=false preview returns.

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

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

The core behavior is front-loaded in the first sentence and the constraint follows immediately. The parenthetical cross-reference to create_time_entry's docstring is only mildly wasteful, and every remaining sentence carries behavioral information.

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

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

For a 9-parameter mutation with no output schema, it covers the non-obvious computation and ordering rules that would otherwise cause failed calls. It leaves the preview-vs-applied result shape and permission prerequisites to the schema's confirm description and annotations.

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

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

Schema coverage is only 33% (9 params, most undocumented), and the description compensates for the critical pair — it explains that end_time is never transmitted and is converted to hours, and that start_time defines the base. However, required parameters activity, spent_on, and the optional user/comment remain unexplained in both places, leaving a real 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 and resource ('Create a time entry') plus the distinguishing mechanism ('by start/end time instead of a duration'). It explicitly names the sibling it differs from (create_time_entry / ongoing entries), so an agent can route between them without opening either schema.

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

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

The closing sentence gives a clear selection rule: known end time → this tool, ongoing entry → create_time_entry. It does not address the update counterparts (update_time_entry, update_time_entry_until), so the routing guidance is clear but not exhaustive.

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

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

Annotations already cover the safety profile (non-readOnly, non-destructive, non-idempotent, open-world). The description adds genuinely non-obvious behavior: a rejected validation preview is not an MCP error, so the agent must inspect ready/validation_errors in the result. It omits permission requirements and the duplicate-version risk implied by idempotentHint=false.

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

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

Two short, front-loaded sentences with no filler. The error-handling caveat is worth its space, though the line-broken formatting makes it slightly harder to scan than a single tight clause.

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 an 8-parameter mutation tool with no output schema, the description discloses the result fields that matter (ready, validation_errors) but leaves out permission requirements, what a version conceptually is, and any note on side effects. It is adequate but not complete.

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

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

Schema coverage is 100% with per-parameter descriptions (name length, status/sharing values, confirm semantics, date format), so the schema carries the parameter burden. The description adds nothing parameter-specific; 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?

"Create a version for a project" names a specific verb and resource, and with only create_version/update_version/delete_version/list_versions in the sibling set, the create action is unambiguous. It stops short of differentiating itself from the sibling tools or saying what a version is in this system.

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?

Nothing states when to use this versus update_version or how to obtain the required project/name values. The confirm/preview note hints at a workflow but is framed as error interpretation, not as when-to-use guidance or prerequisites.

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/openWorld/non-idempotent annotations, it discloses non-obvious behaviors: validation is previewed before applying, built-in due-date shifting on non-working days with no opt-out, non-tool-error validation rejections that surface in `ready`/`validation_errors`, and server-completion-order ID assignment. These are exactly the behavioral traits an agent could not 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 purpose, then a dense sequence of parameter and behavior notes; nearly every sentence carries unique information (duration examples, due-date shift, concurrency ordering). Some sentences are long and wrapped awkwardly, but nothing 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?

No output schema exists, and the description compensates by telling the agent to inspect `ready`, `validation_errors`, and `result.due_date` in the result. For a 19-parameter mutation tool this is close to complete, with the main residual gap being coverage of structural fields (type, project, custom_fields) whose id/name resolution rules are unstated.

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

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

With only 11% schema description coverage across 19 parameters, the description carries most of the burden and does well for the trickiest ones: parent id vs display_id, assignee 'me'/numeric with list_users lookup, ISO8601 duration syntax with examples, and the target_versions/version mutual exclusivity with an explicit empty-list semantic. Unexplained remain project, type, subject, priority, responsible, category, custom_fields, project_phase, and the preview/confirm workflow (though the schema documents confirm).

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

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

The first line names the verb and resource directly ('Create a work package'), and later sentences distinguish it from create_subtask and bulk_create_work_packages in the concurrency/id-ordering context. It does not explain when to prefer create_subtask (child creation) over this tool, so differentiation from siblings is partial rather than complete.

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

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

It gives concrete routing advice: call list_users to resolve assignee ids, and use bulk_create_work_packages when relative ID creation order across a batch matters. There is still no explicit guidance on create_subtask vs this tool for nested creation beyond the parent-parameter note, and no prerequisites/permission guidance.

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

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

Beyond the annotations, the description discloses critical non-obvious behavior: OpenProject stores only one canonical relation type per pair, silently rewrites certain requested types, and may swap from_id/to_id relative to the input. It also instructs the agent to read the actual type and IDs from the response rather than assume they match the request. This is exactly the kind of behavioral context annotations cannot provide.

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

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

The description is front-loaded with the core action and then provides dense, relevant detail about relation_type behavior. It is appropriately sized for a mutation with surprising canonicalization semantics, though the long run-on sentence about rewriting and swapping could be structured more readably.

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

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

For a mutation tool with no output schema, the description covers the most important behavioral risk: canonical type rewriting and ID swapping. The schema already documents the confirm preview behavior, but the description omits usage guidance and does not explain the lag parameter, leaving minor gaps.

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

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

The description adds substantial meaning beyond the schema by enumerating the accepted relation_type values and explaining how work_package_id and related_to_work_package_id map to from_id/to_id, including the swap behavior. It does not explain the lag or description parameters, so there is still a gap, but the most consequential parameter semantics are covered.

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

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

The description opens with a specific verb and resource: 'Create a relation between work packages.' That clearly identifies the operation. It does not explicitly differentiate itself from siblings such as update_relation, delete_relation, or get_work_package_relations, so it falls short of the top score.

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

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

The description does not state when to use this tool versus alternatives such as update_relation or delete_relation. It also does not mention prerequisites, when to avoid creating a relation, or the preview/confirmation workflow described in the schema. Usage must be inferred from the verb alone.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral facts beyond that: the unique-active-reminder constraint with its failure mode, the ISO 8601 format with an example, and the OpenProject 16.1+ requirement.

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

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

Three short, front-loaded sentences with zero filler: format, constraint, and version prerequisite in that order. Every sentence carries actionable information.

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

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

For a mutation tool with annotations and no output schema, the description covers the key failure mode, format, and version requirement. The confirm/preview mechanism is documented in the schema, but the unexplained 'note' parameter leaves a small gap.

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

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

Schema coverage is 50%; work_package_id and confirm already have schema descriptions, and the description usefully documents remind_at's ISO 8601 format. The 'note' parameter remains unexplained in both schema and description, so compensation is only partial.

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 ('Create a reminder on a work package'), so the operation is unambiguous. It does not explicitly differentiate from siblings like update_reminder or list_reminders, but the name's verb conveys the distinction.

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

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

The description gives the 'one active reminder per work package' constraint and a version prerequisite (16.1+), which helps avoid errors. However, it never says when to use this versus update_reminder or delete_reminder, leaving alternative routing implicit.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), and the description adds real value beyond them: a hard version prerequisite (17.7+) and the failure signal ([not_found] naming the required version). It does not restate the preview/confirm two-phase behavior, which is documented in the schema, so this sits just below the top.

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 action and the version caveat, then parameter notes in a tight per-parameter layout. Every sentence carries information, though the trailing warning about list_work_package_wiki_links is slightly tangential to the create call itself.

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 4-param mutation with no output schema, the description covers prerequisites, error behavior, and the two undocumented parameters. The one remaining gap is what a successful call (or the confirm=false preview) returns, which the description does not describe and no output schema supplies.

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 only 50% (provider and identifier are undocumented in the schema), and the description fills exactly that gap: identifier is the page identifier at its provider and must be the numeric wiki_page_id for the internal wiki; provider is the provider's universal identifier such as 'internal'. It even flags the non-obvious trap that a non-resolving link breaks list_work_package_wiki_links.

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 + resource in the first sentence: 'Create a link from a work package to a wiki page.' It also names the related siblings implicitly (get_wiki_page, list_work_package_wiki_links) and the counterpart delete tool is obvious from the name, so an agent can distinguish it from the read/delete variants 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 concrete pre-call routing: get the identifier from get_wiki_page's wiki_page_id when using the internal wiki, and check the server version since older servers return [not_found]. It lacks an explicit 'use this instead of X when…' exclusion, but the workflow context is clear enough to act on.

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, readOnlyHint=false, and idempotentHint=true, so the safety profile is structured. The description's 'cannot be undone' reinforces irreversibility but adds nothing about the mandatory preview/approval flow, permission requirements, or side effects on related work package data, which are the details that would genuinely help.

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

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

One short clause, front-loaded with the action and consequence, with zero filler. Its brevity is intentional, though it borders on under-specification given the irreversible nature of the operation.

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

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

With rich annotations, a fully documented two-parameter schema, and no output schema, the essentials are present. What's missing is behavioral framing beyond 'cannot be undone' – notably that the call is a no-op unless confirm=true and that user approval of the preview is expected – which the agent must discover from the schema alone.

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 carry meaningful descriptions, including the crucial confirm-preview semantics. The tool description adds no parameter-level information, so it sits at the baseline for a fully documented 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 ('Delete') and resource ('attachment'), so the operation is unambiguous. It does not distinguish itself from other deletion siblings (delete_news, delete_reminder, delete_work_package) beyond the resource name, but the resource word is enough to disambiguate here.

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

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

There is no guidance on when to use this versus get_attachment, list_work_package_attachments, or any restoration path. The preview-then-confirm workflow lives only in the schema's 'confirm' description, not in the tool description, so the description itself gives no procedural context.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the baseline is low, yet the description adds two non-obvious facts: the action is irreversible and dependent grid columns are left pointing at a deleted query. It does not describe what the preview (confirm=false) returns, which is the one remaining behavioral gap.

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

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

Two sentences, front-loaded with the irreversible verb and resource, followed by the sibling routing and the side-effect caveat. No restatement of the name or schema content.

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

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

For a destructive two-parameter tool with no output schema, the description supplies the key facts: permanence, naming disambiguation, and the cross-entity consequence. Only the preview return behavior and any deletion-blocking conditions are omitted, and part of that lives in the schema.

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

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

Schema coverage is 100% and both parameters are documented in-schema, including the confirm=false preview vs. confirm=true apply protocol and where board_id comes from. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete one saved work package query') and disambiguates 'board' as a saved query, which is the main naming ambiguity. It also names delete_grid as the tool for the adjacent grid concept, so an agent can tell the siblings apart without reading schemas.

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

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

The second sentence routes the agent away from this tool when the target is actually a board grid ('board grids themselves are deleted with delete_grid'), giving an explicit alternative. It stops short of stating preconditions for deletion (e.g., ownership or use-in-grid restrictions).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real value by clarifying the blast radius: the action is irreversible yet the actual file in external storage survives. It omits the two-step preview/confirm behavior, which is a notable gap for an irreversible operation, but that is documented 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?

A single compact sentence that front-loads the operation and appends the two facts that matter most (irreversibility, file retention). No waste.

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

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

Output schema exists, so return values need no explanation, and the schema fully documents both parameters. The one missing piece is routing guidance among the many delete_* siblings, but for a simple two-param mutation the definition is otherwise sufficient.

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

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

Schema description coverage is 100% – file_link_id points to list_work_package_file_links and confirm spells out the preview/apply semantics. The description contributes nothing about parameters beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (delete a file link) and immediately scopes the effect by noting the underlying file remains in external storage, which distinguishes it from delete_attachment. It does not explicitly name the sibling tools, so differentiation is implied rather than stated.

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

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

Usage is implied by the destructive nature and the 'file link only' scope, but there is no explicit when-to-use/when-not or reference to alternatives such as delete_attachment or delete_work_package_wiki_link. The preview/confirm workflow is delegated entirely to the schema.

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 and idempotentHint, so the description adds real value by disclosing irreversibility and the cascading removal of column queries in 17.0+. It stops short of stating permission requirements or what happens when the grid is already gone, and the 'as far as you may delete them' clause is vague about partial cascade.

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 action and the eligibility constraint, then the version note and the irreversibility warning. Two of the sentences are efficient; the 'as far as you may delete them' phrasing is ambiguous filler that costs clarity.

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

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

For a destructive two-parameter tool with no output schema, the description covers the essentials: what is destroyed, what cascades, when it is blocked, and that it is irreversible. The remaining gap is procedural (how to obtain grid_id and the preview-then-confirm flow), which the schema partially covers.

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 only 50%: confirm is documented in the schema but grid_id has no description anywhere. The description never explains where grid_id comes from (e.g., list_grids) or that confirm=false yields a preview, so it does not compensate for the undocumented required 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 ('Delete a board grid') and immediately scopes which grids are eligible, which separates it from delete_board and update_grid without ambiguity. An agent can identify the object being removed and the excluded grid types in one read.

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 the when-not case ('My Page and project overview grids cannot be deleted'), which prevents a class of failing calls. It does not mention alternatives such as update_grid for non-destructive changes or delete_board, so guidance is clear but not complete.

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

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

Annotations declare destructive/idempotent/openWorld, but the description adds genuine context beyond them: the OpenProject 17.4+ requirement, irreversibility of one-time meeting deletion, cancellation emails sent to participants when notifications are on, template rejection, and that occurrences are only cancelled and reset to the series template on restore. These are side effects and preconditions an agent cannot infer from annotations.

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

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

Five short sentences, each carrying distinct load: cascade scope, version gate, reversibility, series semantics, and the routing alternative. The destructive caveat is front-loaded and nothing is repeated.

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?

No output schema exists, yet the description covers what an agent needs to call this safely: side effects, irreversibility, permission/version precondition, the series edge cases, and which sibling to use instead. The preview-then-apply confirm contract is handled by the schema, leaving no meaningful gap.

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

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

Schema coverage is 50%: the confirm flag is well documented in the schema itself, while meeting_id has no description in either place. The text implies the identifier distinguishes a meeting, an occurrence, or a series template, but never says how to obtain a meeting_id (e.g., via list_meetings) or what a rejected template call returns.

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

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

States a specific verb and resource plus the full cascade footprint ('with its agenda, outcomes, attachments and the time entries logged on it'), so the blast radius is clear from the first sentence. It is cleanly distinguishable from delete_recurring_meeting, which it explicitly routes to.

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-not conditions and named alternatives: the template meeting of a series is rejected, and deleting the whole series requires delete_recurring_meeting instead. It also explains that an occurrence is merely cancelled and that init_recurring_meeting_occurrence restores it, which tells the agent exactly what this call does and does not achieve for each meeting type.

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: annotations only say destructive=true, whereas the description discloses that outcomes are cascaded away, that the operation is irreversible, that closed meetings are rejected, and that a server version is required. These are the exact behavioral facts an agent needs before invoking a destructive call.

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

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

Three short sentences, front-loaded with the action and its cascade effect, followed by environment and state constraints. Zero filler.

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

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

For a destructive two-parameter tool with no output schema, this covers irreversibility, cascade scope, and state preconditions. The remaining gap is the required identifier and the preview/confirm flow, the latter being handled by the schema's own parameter description.

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

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

Schema coverage is 50%: the confirm parameter is well documented in the schema, but the single required parameter agenda_item_id has no description anywhere, and the description adds no clarification about what an agenda item id is or where to obtain it.

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

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

States a specific verb and resource (delete a meeting agenda item) plus an important scope detail: outcomes are deleted with it, which distinguishes it from the sibling delete_meeting_outcome. It does not, however, name any alternative tool explicitly.

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

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

Provides preconditions (OpenProject 17.6+, rejected while the meeting is closed) which help the agent predict failure, but gives no guidance on when to choose this over update_meeting_agenda_item or delete_meeting_outcome, and no mention of the preview/confirm workflow referenced by the schema.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so 'this cannot be undone' largely restates structured data. The one piece of net-new context is the version requirement (17.6+), which the annotations cannot express. The preview-then-apply safety workflow implied by the confirm parameter is left to the schema.

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

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

Two short sentences, front-loaded with the action and the irreversibility warning. It is efficient, though borderline under-specified for a destructive operation with a two-step confirm flow.

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?

Rich annotations plus a schema-documented confirm parameter cover most of what an agent needs, and no output schema is expected here. Still missing is an explicit statement of the preview/apply workflow and any note on entity identification for outcome_id, which matters for an irreversible delete.

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 only 50%: confirm is well documented in the schema, but outcome_id has no description anywhere. The tool description says nothing about either parameter, so it does not compensate for the gap — it never clarifies that confirm=false is a no-op preview and true performs the irreversible delete.

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 (delete) and resource (meeting outcome), so the agent knows exactly what entity is affected. It does not distinguish itself from the sibling tools create_meeting_outcome or update_meeting_outcome, though the delete verb does most of the disambiguating work.

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

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

The only usage signal is the prerequisite 'Requires OpenProject 17.6+', which is genuinely useful but constrains feasibility rather than telling the agent when to choose this over update_meeting_outcome. There are no explicit exclusions or alternative-tool routing.

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

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

Annotations already flag destructiveHint=true, but the description adds substance beyond them: children are deleted rather than moved, the action cannot be undone, and two specific server-side rejection states are called out. That is exactly the kind of context 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?

Three short sentences, front-loaded with the action and its cascade, followed by prerequisites and irreversibility. No filler; only the version-requirement sentence could be considered secondary.

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-looking mutation with no output schema, the description covers failure modes, reversibility, and side effects well. The remaining hole is identifying the target section, which is left entirely to the schema.

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

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

Schema coverage is 50%: `confirm` is well documented in the schema as a preview-then-apply flag, but `section_id` has no description anywhere. The description never explains what a section id refers to or how to obtain one (list_meeting_sections), so it does not compensate for the coverage 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 (delete) and resource (meeting section) and immediately discloses the cascade: agenda items and their outcomes are deleted, not re-parented. That cascade note is what distinguishes it from delete_meeting_agenda_item or delete_meeting_outcome for an agent scanning siblings.

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

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

Gives concrete preconditions and exclusions: requires OpenProject 17.6+, is rejected while the meeting is closed, and is rejected for the backlog section. It does not name an alternative tool for cases where deletion is blocked (e.g., deleting agenda items individually), so it stops short of full when/when-not routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description adds important behavioral detail beyond annotations: the action cannot be undone, inherited group roles remain, only direct roles are removed, and the call is rejected if all roles are inherited.

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

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

The description is two tight sentences with the core purpose and irreversibility front-loaded, followed by the nuanced group-role behavior. There is no redundant or wasted text.

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 membership mutation, the description provides the essential warning and the group-role edge case. The preview/approval flow is handled by the schema, and no output schema is present, so the definition is nearly complete, with only minor missing context about alternatives.

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 membership_id and the preview/confirm workflow are already documented in the schema. The description does not add parameter syntax or format details beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: delete a project membership, and immediately clarifies irreversibility. It is easily distinguishable from siblings such as update_membership, create_membership, and list_project_memberships.

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

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

The deletion use case is clear, and the rejection condition when all roles are inherited is useful. However, it does not explicitly compare this tool against update_membership or other management alternatives, leaving the agent to infer the choice.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds real context beyond them by disclosing that comments and attachments are destroyed along with the entry and that the deletion is irreversible. It stops short of noting permission requirements or what confirmation the call returns.

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

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

A single front-loaded sentence naming the action, its cascade effects, and its irreversibility. No filler and nothing important buried.

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 tool with full schema coverage, no output schema, and strong annotations, the description supplies the one thing structured data cannot: the cascade and irreversibility. Only minor gaps remain, such as permissions or how to locate a valid news_id.

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 confirm parameter's description already spells out the preview-then-approve workflow, so the schema carries the parameter burden. The description adds nothing about news_id provenance (e.g. that it comes from list_news) or the confirm flag, making this a baseline 3.

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

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

States a specific verb and resource ("Delete a news entry") and adds scope detail about the cascade to comments and attachments. The resource name alone separates it from the many other delete_* siblings, though it doesn't explicitly contrast with them or with update_news/create_news.

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

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

The description gives no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as update_news or list_news for locating the target. The only usage signal is the implicit caution from "cannot be undone," and the confirm-preview workflow lives entirely in the schema rather than the description.

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

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

The description adds substantial behavioral detail beyond the annotations: it explains that the project is archived immediately and deleted in a background job, lists the affected sub-entities (work packages, memberships, versions, etc.), states irreversibility, mentions automatic deletion of storage folders, and describes rejection conditions. This is rich transparency for a destructive operation and is consistent with the provided annotations.

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

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

The description is front-loaded with the core action but becomes wordy and includes a confusing final sentence: 'Unless the project is already archived, rejected while work packages of other projects use one of their versions.' This sentence is grammatically awkward and adds ambiguity. The overall structure could be tightened without losing important 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?

Given the tool's complexity (destructive, asynchronous deletion, open-world), the absence of an output schema, and the annotations covering safety hints, the description provides all necessary context: what gets deleted, irreversibility, background job behavior, and rejection conditions. An agent has enough information to call the tool correctly, including the need to preview via the confirm parameter (documented in the schema).

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

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

Schema description coverage is 100%, so both parameters (confirm, project) are fully documented in the schema. The description adds no additional meaning about the parameters—it does not explain the confirm preview behavior or the project matching rules. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

The description starts with a specific verb and resource: 'Delete a project and its subprojects (admin operation).' This unambiguously distinguishes it from other delete tools (delete_news, delete_work_package, etc.) and from update_project. An agent can immediately understand the tool's purpose.

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

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

The description provides clear context: it is an admin operation that cannot be undone, and it lists conditions when deletion is rejected. It doesn't explicitly state when to use this instead of alternatives (there are no alternatives for deleting a project), but the context is sufficient for an agent to know this is the tool for removing a project. No misleading guidance.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description goes well beyond them by enumerating the cascade (agenda, outcomes, attachments, time entries), stating irreversibility, noting the OpenProject 17.4+ version floor, and disclosing the cancellation emails sent to participants. That is exactly the extra context that matters for a destructive tool.

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

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

Four short sentences, front-loaded with what is destroyed, then version requirement, then cascade and irreversibility, then side effects. No filler and no repetition of the name.

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

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

For a destructive, annotation-covered, two-parameter tool with no output schema, the description covers everything an agent needs: scope, blast radius, irreversibility, version constraint, and notification side effects. Nothing material is left to guesswork.

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

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

Schema description coverage is 100%, and the schema already documents both recurring_meeting_id (sourced from list_recurring_meetings) and the confirm preview/apply flag in detail. The description adds nothing about either parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a recurring meeting series') and immediately scopes it with 'with all its occurrences, past and future', which cleanly separates it from delete_meeting and cancel_recurring_meeting_occurrence. An agent can pick the right tool 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?

The 'all its occurrences, past and future' clause implicitly routes the agent away from the per-occurrence cancel tool and the single-meeting delete tool. It never names those siblings explicitly, nor does it state any prerequisites such as required permissions, so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so irreversibility is partially covered; the description restates it but does add the non-obvious side effect that removing a follows/precedes relation reschedules the successor. That side effect is the strongest contribution. It says nothing about required permissions or what happens to the deleted relation's history.

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

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

Two short sentences, the irreversible consequence front-loaded and the rescheduling caveat second. Zero filler.

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

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

For a destructive two-parameter tool with full schema coverage, no output schema, and rich annotations, this is nearly sufficient: safety and side effects are covered. A mention of permission requirements or failure modes would complete it.

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

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

Schema coverage is 100% and the confirm parameter already documents the preview-then-approve flow thoroughly. The description adds nothing about relation_id sourcing (the schema points to list_relations/get_work_package_relations) or about the default confirm=false preview behavior. Baseline 3.

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

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

States a specific verb (delete) and resource (relation between work packages), which distinguishes it from create_work_package_relation and update_relation by verb alone. It doesn't explicitly name those siblings, but the operation is unmistakable.

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

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

Usage is implied by the destructive framing and the rescheduling note, which hints at when the consequence matters. However, nothing says when to prefer update_relation over delete, or what preconditions (permissions, relation state) apply.

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 and idempotentHint, yet the description adds real value beyond them: irreversibility, the non-obvious side effect that unread notifications are marked read, a creator-only authorization rule, and a minimum server version. That is exactly the kind of hidden behavior an agent needs before committing an irreversible write.

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

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

Two sentences, front-loaded with the action and its irreversibility, then the secondary side effect and constraints. No filler; every clause carries information.

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

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

For a destructive mutation with no output schema, the description covers risk, side effects, permissions, and version compatibility, with annotations covering the safety profile. Only gap is how to source the reminder identifier and a nod to the preview-then-confirm workflow that the schema describes.

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 50%: the confirm preview/approval parameter is well documented in the schema, but reminder_id has no schema description and the description adds nothing about it (e.g., obtain via list_reminders). Baseline 3 is appropriate since the trickier parameter is covered elsewhere, but the description does not 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?

Specific verb (delete) plus resource (reminder) with a meaningful scope qualifier — 'pending' — and an explicit consequence ('so it never fires; this cannot be undone'). An agent can immediately distinguish this from update_reminder or create_work_package_reminder without opening schemas.

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

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

States two hard preconditions: only the creator may call it, and it requires OpenProject 16.1+, which lets an agent rule itself out. It doesn't explicitly say when to prefer this over update_reminder (e.g., to suppress rather than remove) or how to find a reminder_id, so it stops short of full routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the 'cannot be undone' line mostly restates that. It adds no information about permissions, side effects on logged hours/reporting totals, or what the preview returns, which is where a destructive tool would benefit from extra context.

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

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

A single front-loaded sentence with zero filler and the irreversibility warning up front. It is arguably too terse for a destructive operation, but nothing in it 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 two-parameter destructive tool with complete annotations and full schema coverage, the essentials are covered by structured data. However, the description omits the critical operational point that confirm=false is the default and that a preview must be shown to the user before the destructive call, which is the main risk of misuse.

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%: time_entry_id's provenance (from list_time_entries) and the confirm preview/apply semantics are both fully documented in the schema. The description adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (delete a time entry) so an agent can distinguish it from update_time_entry, get_time_entry, and list_time_entries. It doesn't explicitly name which sibling to prefer for non-destructive edits, but the action is unambiguous.

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

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

There is no guidance on when to use this versus update_time_entry, and no mention of the two-step preview/confirm workflow that actually governs invocation. The schema documents the confirm parameter, but the description itself leaves usage entirely implicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds valuable context beyond annotations by stating deletion cannot be undone and by documenting the dependency-based rejection behavior.

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

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

The description is two short sentences with no wasted text. The irreversible nature and the usage restriction are front-loaded, so an agent gets the critical information immediately.

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

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

Given rich annotations, full schema descriptions, and no output schema, the definition is nearly complete for a destructive tool. A minor gap is that it does not explicitly reinforce the preview-first confirm workflow, but the schema already documents that behavior.

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

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

Schema description coverage is 100%, and both parameters are well documented in the schema, including the preview/confirm behavior. The description does not add parameter-level semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: "Delete a version." It clearly distinguishes this from sibling operations such as create_version, update_version, and get_version without ambiguity.

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

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

It gives an explicit rejection condition: deletion is refused while any work package in any project uses the version, including as its "found in" version. That is useful when-not guidance, though it does not explicitly mention alternatives such as checking list_versions or get_version 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 by enumerating exactly what is destroyed alongside the work package and by disclosing version-dependent behavior: pre-17.6 all descendants are deleted, while 17.7+ only deletable descendants go and the rest are re-parented. Combined with the explicit 'cannot be undone' warning, this is precisely the behavioral context an agent needs before a destructive call.

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

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

Two tight sentences: the destructive scope first, then the irreversibility and version caveat. No filler, and the highest-stakes information is front-loaded.

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

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

For a destructive, no-output-schema tool, this covers cascade effects, irreversibility, and version-dependent descendant handling. It is slightly short on operational context such as required permissions or what the preview mode returns, but nothing essential to calling it 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% and the schema itself is unusually rich (the confirm parameter explains preview-vs-apply and the approval step; work_package_id distinguishes numeric id from display id). The description adds nothing about parameters, so the baseline 3 is warranted — the schema, not the prose, does the work.

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 ('Delete') plus resource ('work package') and immediately scopes the cascade (time and cost entries, relations, attachments, history). That makes it trivially distinguishable from siblings like delete_relation, delete_attachment, or update_work_package.

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?

Implicitly frames usage by spelling out the consequences of deleting, but never says when to choose this over alternatives (e.g., detaching a relation via delete_relation, or closing instead of deleting). No explicit prerequisites, permission notes, or when-not-to-use guidance.

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

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

Goes far beyond the annotations: discloses irreversibility, an internal pre-flight list call whose failures propagate as [server_error], version-dependent behavior (17.6+ required, misleading [not_found] on older versions), the required 'Manage wiki page links' permission, and that a permission failure surfaces as 404/[not_found] rather than [permission_denied]. This is exactly the kind of non-obvious failure-mode context 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-loads the action and irreversibility, then layers version, authorization, and link-type constraints. Dense but each block carries information; minor overlap between the version note and the permission note (both explain a not_found naming 17.6) is the only redundancy.

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

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

A destructive mutation with no output schema, and the description covers safety (irreversible), prerequisites (version, permission), failure modes, and preconditions (enumeration must succeed). Nothing an agent needs to avoid a wrong or misread call is missing; the preview/confirm workflow is covered by the schema.

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

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

Schema coverage is 67% and `confirm` is already documented in the schema, but the description adds genuine meaning: `link_id` must come from list_work_package_wiki_links, and `work_package_id` is not merely an ID but the authorization anchor because OpenProject has no single GET for a link. That is real added value over the schema.

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

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

States a specific verb and resource ('Delete a work package's wiki page link') and immediately differentiates from the sibling `list_work_package_wiki_links` and from relation deletion by restricting scope to link_type 'relation'. An agent can identify this tool without opening the schema.

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

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

Gives concrete when-not conditions: inline links are rejected and can only be removed by editing the description text, and relation links must be enumerated via list_work_package_wiki_links first. It does not name the specific sibling tool to use for the inline case, but the routing is strongly implied.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive operation. Beyond that, the description adds important behavior: the query is resolved server-side, no client-side filter translation occurs, and results are filtered against the MCP's OPENPROJECT_READ_PROJECTS allowlist even though the underlying API token has broader permissions.

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 then supplies only supporting details about sourcing query_id, server-side execution, and permission filtering. Every sentence contributes specific information without repetition.

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

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

There is no output schema, so the description carries some burden for return behavior; it says resolved work packages are returned but does not describe the result shape. It does however explain the important filtering and permission behavior, which covers the tool's most consequential semantics.

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 only 67%, and query_id has no schema description. The description compensates well by explaining that query_id is the query's numeric id and can be sourced from get_view/list_views or from a board, where the board id is the underlying query id. Pagination parameters are already documented in the schema, so the added value is concentrated on the required parameter.

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

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

The first sentence states a specific verb and resource: execute a saved OpenProject query by id and return resolved work packages. It also distinguishes itself from definition-returning siblings such as get_view/list_views by emphasizing that real work packages are returned server-side, not just the query definition.

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

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

The description clearly explains how to obtain the required query_id from get_view/list_views or from boards, which gives strong usage context. It does not explicitly exclude alternatives like list_work_packages or search_work_packages, so it falls short of a full when-to-use/when-not-to-use comparison.

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, openWorldHint and destructiveHint=false, so the safety profile is fully covered without the description. The description adds no behavioral context of its own — it does not clarify whether the result is metadata or binary content, which is the one ambiguity that matters here given the sibling get_attachment_content.

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

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

A single short, front-loaded sentence with zero waste. It is arguably under-specified rather than over-long, but as a sizing judgement the text is efficient.

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

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

An output schema exists so return values need not be explained, but the definition leaves the metadata-vs-content distinction with get_attachment_content entirely unresolved, which is the main invocation risk for this tool in this sibling set.

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 0%, but there is only one parameter, an integer named attachment_id, whose meaning is self-evident. The description's 'by id' merely restates the schema and does not say where the id comes from (e.g., list_work_package_attachments), so it neither hurts nor compensates much.

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 with scope ('a single attachment by id'), so the agent knows it is a single-item retrieval rather than a list. However it does nothing to distinguish itself from the closely named sibling get_attachment_content, and an agent cannot tell from the text whether this returns metadata or the file itself.

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

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

There is no guidance on when to use this versus get_attachment_content or list_work_package_attachments, which are the obvious alternatives in the sibling set. The description offers no context, preconditions, or exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive context beyond them: outcome values (text, too_large, not_inline_supported), the byte-limit refusal behavior, truncation flag, and the assurance that nothing is written to disk. This is a rich behavioral disclosure that a caller could not infer from annotations.

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

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

Front-loaded with the core purpose, then well-organized bullets mapping each outcome. Most content earns its place, though the aside about content_type naming the file where the served header says 'not inlineable' is fairly deep detail that could be trimmed without losing caller-critical 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?

No output schema exists, so explaining the return block shape, outcome enumerations, truncation, and refusal semantics is essential — and all are covered. A caller has everything needed to invoke it and interpret results correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it does: max_bytes is explained as a downward-only cap tied to the server-configured OPENPROJECT_ATTACHMENT_CONTENT_MAX_BYTES (5 MB default) with the rule that it never raises the limit. attachment_id is self-evident from the resource context. This meaningfully exceeds what the bare schema conveys.

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 (read) and resource (attachment content) with the crucial qualifier 'not just its metadata,' which separates it from the sibling get_attachment at a glance. An agent can distinguish the two without inspecting schemas.

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

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

Explicitly routes metadata-only requests to get_attachment and explains the content-retrieval path in detail (inlined image vs text vs refused vs metadata-only). The alternatives and conditions are named, not implied.

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

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

The annotations already fully declare the safe read-only, idempotent, non-destructive behavior. The description adds meaningful context by stating the OpenProject 17.6+ version requirement, which is not captured in annotations, but it does not describe error behavior or response characteristics.

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

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

Two short sentences with the core action front-loaded and the version constraint clearly separated. Every sentence carries useful information, with no redundant wording.

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

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

An output schema exists, so the description need not explain return values, and the simple one-parameter read shape is adequately framed. The main remaining gap is not linking this tool to list_backlog_buckets or explaining where to source the id.

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 0%, so the description must compensate, but 'by id' only restates the parameter name and does not explain format, range, or where to obtain a backlog bucket id. The schema supplies the integer type and required constraint but nothing further.

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 gives a specific verb-resource pair: get a Backlogs backlog bucket by id. This distinguishes it from list_backlog_buckets, which is a collection-level sibling, though it does not explicitly name or contrast with that 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?

The description states no when-to-use guidance or alternatives. It only adds a version prerequisite, leaving the agent to infer that this is for retrieving a single bucket when its id is known rather than listing buckets.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only that the object is 'saved' and looked up by id; it says nothing about not-found behavior, permission requirements, or whether the returned object includes work packages or query state.

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

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

A single short sentence with no filler, and the retrieval key is front-loaded. It is efficient, though the brevity contributes to the missing sibling differentiation and parameter detail rather than reflecting a deliberate minimal specification.

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-value explanation is not required, and the annotations cover safety and world assumptions. However, with a schema that gives no parameter description and multiple overlapping siblings, the definition is only minimally sufficient to call the tool correctly and does not resolve the board vs. query vs. grid ambiguity.

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

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

Schema description coverage is 0% for the single required parameter board_id, so the description must carry the burden. It only says 'by id', without explaining the id format, where to obtain it (e.g., list_boards), or whether it accepts query or board identifiers. That is closer to restating the parameter name than adding meaning.

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

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

The description gives a specific verb ('Get') and resource ('saved OpenProject board/query') plus the lookup key ('by id'), so an agent can tell this is a single-item fetch rather than a list. It does not distinguish the tool from near-siblings like get_grid, get_view, or execute_query, and 'board/query' blurs whether this returns a board or a query object.

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

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

There is no guidance on when to use this versus list_boards, list_grids, get_view, or execute_query, nor any prerequisite about where a board_id comes from. The phrase 'saved ... by id' implies a retrieval scenario but gives no explicit conditions or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral information: the optional project is validated against the category's real project and a mismatch yields a not-found error rather than acting as an authorization scope. That is non-obvious error semantics an agent cannot get from the structured fields.

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

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

Two short sentences, front-loaded with the core action, followed by the one subtle parameter rule. No filler or repetition of schema/annotation content.

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

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

With an output schema present there is no need to describe return values, and annotations cover the read-only/idempotent profile. The description covers the one genuinely tricky element (project validation). Minor gap: it doesn't state what happens for a nonexistent category_id or a permission failure, but the essential call-shaping information is present.

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

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

Schema coverage is 50% — project has a description, category_id does not. The description compensates by explaining the exact semantics of the under-documented project parameter: it is a cross-check, not an authorization source, and mismatches surface as not-found. This is meaning beyond the schema's 'id, or name' note.

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: 'Get a single category by id.' The word 'single' implicitly distinguishes it from list_categories, but the sibling is never named, so the differentiation is inferential rather than 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?

Usage is only implied by 'single category by id' — an agent can infer this is a fetch-one-vs-list-many tool, but the description never says when to prefer it over list_categories or what happens when the id doesn't exist (aside from the project-mismatch case).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description's only addition is that the resource has no create/update/delete endpoint in Community Edition, which usefully stops an agent hunting for a write tool but is largely a restatement of the read-only hint. Nothing is said about error behavior for a missing id or about pagination/scope.

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

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

Two short sentences with the core operation front-loaded, and no filler. The second sentence is mildly tangential to invocation but is short and adds context, so it earns most of 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?

With an output schema present, return values needn't be described, and the annotations cover safety and idempotency. For a single-parameter lookup the description is close to sufficient; the only real gap is how to obtain a valid cost_entry_id and its relationship to list_work_package_cost_entries.

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 0% for the single required parameter, so the description must carry the burden; it only says "by id," which is a restatement of the parameter name cost_entry_id. It adds no format, range, or sourcing guidance (e.g., where to obtain a valid id).

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?

"Get a single cost entry by id" states a specific verb and resource, and the word "single" implicitly contrasts with the list variants among the siblings (list_work_package_cost_entries, get_work_package_costs_by_type). It never names an alternative explicitly, so sibling differentiation is implied rather than stated.

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

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

The description implies the lookup use case (fetch one entry when you already have an id) but gives no explicit when-to-use guidance and does not tell the agent to prefer a list endpoint when the id is unknown. There are no stated prerequisites or exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely new context: the entire cost-type resource is immutable in the upstream API, not just this call, and there is no collection endpoint. That scope information is not derivable from the annotations.

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

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

The core action is front-loaded in the first sentence, and the second paragraph is short and purposeful, preempting a likely wrong instinct (searching for a list tool). The parenthetical "(no list_cost_types tool exists because the endpoint does not exist upstream)" is slightly redundant but earns its place as a guardrail.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile; the description fills the remaining conceptual gap about the resource's immutability. Only the provenance of cost_type_id is unaddressed, a minor omission for a one-parameter lookup.

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 0% for the single cost_type_id parameter, and the description adds only "by id" — no format, range, or where to source a valid ID. With one required parameter, the description should compensate more than a bare restatement of the name.

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 ("Get a cost type by id") and goes further by explaining why apparent siblings are absent: cost types are read-only with no collection GET, so no list_cost_types exists. An agent can immediately tell this is a single-resource lookup, not a list or mutation.

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 rules out create/update/delete and list variants, preventing the agent from hunting for nonexistent endpoints or attempting writes. It stops short of saying where a valid cost_type_id comes from (e.g. via get_work_package_costs_by_type), which would complete the routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds that the subject is the *authenticated* user, implying an auth/session requirement. It does not cover rate limits or whether the profile shape varies by account type, so it adds modest value beyond 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?

One sentence, front-loaded with the verb and resource, with zero filler. Nothing is wasted and nothing important is buried.

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 zero parameters, a full output schema, and rich annotations, the description needs only to establish what the tool returns and about whom. It does that; only a note on the authentication prerequisite or behavior when unauthenticated would improve it.

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

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