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

Annotations flag a non-read-only, non-idempotent write, and the description adds substantial context: the 'manage agendas' permission requirement, meaning of 403 and 422, the fixture that itemType is create-only upstream, and append-to-last-section behavior. No contradiction with annotations.

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

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

The description is well-structured with clear sections: purpose, examples, return value, pitfalls, and cross-references. It is front-loaded with the core purpose and every sentence adds useful information without fluff.

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

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

For a 5-parameter mutation tool with an output schema, the description covers usage rationale, return shape, error semantics, and all relevant sibling tools. The output schema exists, so the return-value summary is appropriately supplementary.

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?

Input schema coverage is 100% and each parameter already has a rich description (e.g., work_package_id effect, duration_minutes limits, meeting_id append behavior). The tool description offers examples and pitfall context but does not materially extend parameter-level semantics beyond the schema, 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 opens with a specific verb ('Add') and resource ('one item to a meeting's agenda') plus an optional work-package pin. It clearly distinguishes itself from sibling tools by naming update, delete, and outcome-related alternatives in the cross-references.

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

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

It explicitly says 'Use it to build or extend an agenda' and provides concrete usage examples. Cross-references specify when to use get_meeting, update_meeting_agenda_item, delete_meeting_agenda_item, and add_meeting_outcome, and it explains error conditions (403/422) for troubleshooting.

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

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

Discloses critical behavioral traits beyond annotations: the timing state machine with a validation error, the 'backlog section' refusal, the 'manage outcomes' permission causing 403, and the OpenProject <17.6 404 quirk. It also specifies the exact return payload shape. Annotations only set hints (readOnlyHint=false), but the description adds real operational context with no contradictions.

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

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

The description is long but every sentence carries weight. It is front-loaded with purpose, then flows into mechanics, return value, and a dedicated 'Pitfalls' section. For a tool with state constraints and cross-references, this structure is efficient and scannable, not padded.

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

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

Given the tool's complexity (meeting state dependency, multiple kinds, permissions, version quirks), the description covers all necessary context: what it does, how to use it, when it fails, what it returns, and how it relates to siblings. The output schema is also explained explicitly enough that a complete picture is provided with minimal reliance on the structured 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 already covers all four parameters with meaningful descriptions, but the description enriches them with concrete usage examples (e.g., 'decision: ship on Friday' becomes kind='decision' with text in notes) and clarifies the relationship between kind, notes, and work_package_id. It also notes that agenda_item_id is not the meeting id, adding beyond the schema.

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

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

The description opens with a specific verb+resource ('Record an outcome against an agenda item') and immediately enumerates the exact kinds of outcomes (decision, note, follow-up ticket). It distinguishes itself from sibling tools by framing itself as the way to write minutes through the API, with explicit cross-references to get_meeting and update_meeting_outcome/delete_meeting_outcome.

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

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

Provides explicit when-to-use context: it is for writing minutes during an 'in_progress' meeting state, before which and after closure all writes fail. It names the required prerequisite (update_meeting to set state) and the permission ('manage outcomes'), plus points to update_meeting_outcome/delete_meeting_outcome for corrections. This goes far beyond vague 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 indicate non-idempotent behavior, but the description goes further by warning that every call creates a new comment and should not be blindly retried after a timeout. It also discloses the version-specific internal flag pitfall and clarifies that notify=false only suppresses notifications while the comment remains visible.

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

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

The description is well-structured with sections for main usage, pitfalls, and cross-references. Every sentence carries useful information; no filler or redundancy exists.

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

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

Despite having an output schema, the description still notes the return shape and id reuse potential. It covers non-idempotence, version constraints, notification behavior, and alternative tools, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema. It explains the non-idempotent nature of the call (relevant to retries), the subtle behavior of internal=true on older OpenProject versions, and the exact meaning of notify=false. This enriches the parameter understanding.

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

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

The description opens with a specific verb and resource: 'Post a comment on a work package.' It clearly distinguishes this tool from siblings by cross-referencing list_work_package_comments, update_work_package, and upload_attachment, and by contrasting it with edit_work_package_comment.

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

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

Explicitly states when to use the tool: 'reply in a ticket's thread, record a decision, or leave a handover note.' It also provides direct alternatives: use update_work_package for field changes and upload_attachment for files, and read the thread with list_work_package_comments before retrying.

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

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

The description discloses idempotency ('Calling twice is harmless: the second call reports changed: false'), permission requirements, and error behavior (422 on user visibility violation). These go well beyond the annotations (idempotentHint, etc.) and add valuable behavioral context. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place. It uses clear sections (purpose, usage, return value, pitfalls, cross-references) and front-loads the main action. No fluff or repetition.

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

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

Despite having an output schema, the description still summarizes the return values. It covers prerequisites, error conditions, permissions, idempotency, and related tools. For a tool of moderate complexity with two parameters and a clear output schema, this is fully 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 detailed parameter descriptions already. The description adds extra nuance for user_id (the 'me' string is not accepted, permission differences when adding oneself vs. others) and for work_package_id (source of valid IDs). This elevates it slightly above the high-coverage baseline.

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

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

The description opens with a specific verb+resource: 'Subscribe a user to a work package's notifications.' It clearly distinguishes the tool from siblings by contrasting watching with assignment ('Watching is not assignment — use update_work_package(assignee=...) for that') and cross-referencing remove_work_package_watcher as the reverse operation.

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

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

Explicitly states when to use: 'Use this when someone should be kept in the loop on a ticket without being assigned to it.' It also provides exclusions (assignment use case), alternatives (remove_work_package_watcher), and prerequisite conditions (user must have view access, permission needed for adding others). This is a model of 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?

The description goes far beyond the annotations by detailing side effects (may email participants with `notify` set), recovery semantics, exact-instant matching pitfalls, conflict error meaning, idempotent success, and required permissions. This fully discloses the operational 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 dense yet well-organized: opening summary, use case, pitfalls, and cross-references. Every sentence adds meaningful detail; no filler words. It front-loads the core purpose and then layers nuance logically.

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

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

The description covers permission requirements, error semantics, idempotency, side effects, recoverability, and exactly references related tools. With an output schema present, the return confirmation is briefly described without over-explaining. Nothing 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?

Even though schema coverage is 100%, the description enriches each parameter with critical context: `start_time` must be copied verbatim, exact matching is required, and wrong times create phantom stubs. `recurring_meeting_id` is explicitly distinguished from a meeting id. This adds real value beyond the schema.

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

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

The description clearly states the tool cancels one occurrence of a series, distinguishing it from deleting the entire series. It explicitly contrasts with `delete_recurring_meeting` (end series) and `delete_meeting` (instantiated occurrence), making the purpose unambiguous.

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

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

The description gives concrete use cases ('no sync next Monday'), explicitly names alternatives (`init_recurring_meeting_occurrence`, `delete_meeting`, `delete_recurring_meeting`), and provides fallback behavior for conflict errors. This is exemplary guidance on when to use this tool vs. siblings.

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

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

The description extensively discloses behavioral traits beyond the annotations: copying is asynchronous, the tool returns a scheduled response and never claims the copy exists, the job may take minutes, permission requirements (403 meaning), and what is and isn't copied (time entries and comment histories are not). Annotations only indicate mutating and non-idempotent behavior, so the description carries the full burden and does so thoroughly.

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

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

The description is well-structured and front-loaded: purpose, usage scenario, async behavior, pitfalls, and cross-references are each in logical paragraphs. Every sentence adds value; length is justified by the tool's complexity. No redundancy with schema or annotations.

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 (async job, permission requirements, default flags, cross-tool dependencies), the description is remarkably complete. It explains the return shape, how to poll for status, what the job reports, and even mentions the underlying POST /projects/{id}/copy/form call to explain validation behavior. The existence of an output schema means return-style details are not required, and the description still covers behavioral and procedural aspects.

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?

Despite 100% schema coverage, the description adds crucial meaning beyond the schema: id_or_identifier is explicitly the template project, new_name's derived identifier is reported by get_job_status, include_work_packages explains the shell vs. full copy, and notify explains the impact on email volume. This extra semantic context is valuable and not merely schema repetition.

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

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

The description states a clear, specific verb and resource: 'Copy a project — its settings, and optionally its work packages — into a new one.' It also distinguishes this from related tools by noting it is the only way to reproduce members, versions, categories, and enabled modules in one call, differentiating it from create_project and update_project.

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

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

The description provides explicit when-to-use guidance: 'Use it to spin a new engagement or release off a template project.' It also gives exclusions and alternatives in the cross-references section, naming create_project for an empty project, get_job_status for following the async job, and list_projects/get_project for confirming the result. This is model guidance.

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

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

The description adds significant behavioral context beyond annotations: it reveals the POST /meetings/form endpoint behavior (violations naming the attribute), draft state pitfall, lack of invitation emails, timezone storage semantics, and non-support for recurring meetings. This complements the annotations (readOnlyHint=false, idempotentHint=false) without contradiction.

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

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

The description is well-structured with a purpose statement, usage context, pitfalls, and cross-references. While moderately long, every sentence conveys essential operational information—no filler or repetition of schema fields. Front-loaded with the action and key use case.

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

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

With a rich output schema and sibling context, the description fully covers the tool's behavior: return shape (same as get_meeting with empty agenda_items), how to add agenda items, and all necessary cross-references (list_projects, search_principals, update_meeting for state). It equips the agent to use the tool correctly end-to-end.

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

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

The input schema already has 100% coverage with thorough descriptions for each parameter. The description adds extra value by explaining the timezone requirement for start_time, the view-meetings permission for participants, and the ISO duration conversion for duration_minutes, enriching the schema's 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 opens with a specific verb+resource: 'Schedule a meeting in a project and optionally invite participants.' It clearly distinguishes from sibling tools by explicitly stating recurring meetings are not supported (use create_recurring_meeting) and referencing add_meeting_agenda_item for agenda building.

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

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

Provides explicit usage context ('Use it for "book a review on Thursday" style requests'), prerequisites (project must have Meetings module, permissions), and exclusions (recurring meetings). Cross-references to list_projects and search_principals give concrete guidance for finding required parameter 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?

Goes far beyond the basic annotations by disclosing server-set author, member notifications, permission requirements ('manage news'), 403 semantics, no draft state, immediate public visibility, and that the returned id feeds update/delete tools. This rich behavioral context is not present in 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 long but well-structured: one-sentence purpose, usage, return shape, pitfalls, and cross-references. Every section earns its place; the pitfalls are essential. While not ultra-short, the length is justified by the tool's complexity and failure modes.

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

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

Covers all bases: purpose, usage, expected output, permissions, edge cases (403, blank title), API behavior (no draft, immediate public), and relationships to sibling tools. The output schema is explained with the returned fields and how the id is consumed. Very complete for a create operation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful extra context: project_id cannot be changed afterwards, title blank-check happens before the request, summary is plain text not markdown, and description supports markdown. This goes beyond the schema's own field descriptions.

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

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

The description opens with a specific verb and resource: 'Publish a news announcement in a project.' It clearly defines the scope (project overview page) and explicitly distinguishes this from work packages ('News is not a work package'), making it easy to identify against siblings like create_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?

Provides explicit when-to-use guidance: 'Use it for release notes, a weekly report, a maintenance window — anything the whole project should see on its overview page.' It also names an alternative: 'use create_work_package instead' for assignable/trackable items, and cross-references list_news/update_news/list_projects.

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

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

Beyond the annotations, the description reveals critical behavior: it runs POST /projects/form first, returns violations instead of opaque failures, uses the derived identifier verbatim, requires specific permissions (403 meaning), and notes that members are not copied. This significantly exceeds what annotations alone provide, with no contradictions.

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

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

The description is well-structured with clear paragraphs for usage, return value, pitfalls, and cross-references. Every sentence carries useful information such as permission caveats, derived identifier behavior, and sibling tool links. It is appropriately sized for a complex creation tool 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?

Given the tool's complexity (6 parameters, output schema, cross-tool dependencies), the description is comprehensive. It covers the return format, notes to keep the id, explains permission pitfalls, warns about default modules/types, and directs to get_project_metadata for valid values. The output schema exists, so detailed return documentation isn't needed, but it still provides a useful summary.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds extra value by explaining the form-endpoint validation for parameters, explicitly linking parent_id to subprojects, and noting that the identifier is derived from name. However, most parameter meaning already lives in the schema, so the added semantic layer is modest.

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

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

The description opens with 'Create a project' and specifies the resource and action clearly, then differentiates from siblings by mentioning subprojects via parent_id and cross-referencing list_projects, update_project, and get_project_metadata. This makes the tool's unique purpose unambiguous.

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

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

Explicit guidance is provided: 'Use it for a new workspace or, with parent_id, for a subproject of an existing one.' It also names alternatives and related tools in the cross-references section, such as list_projects for finding parent IDs and update_project for later changes, giving clear when-to-use and when-not-to-use context.

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

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

The description discloses extensive behavioral traits beyond annotations: local validation of frequency/end_after combinations, template created as DRAFT, time_zone overwrite and follow-up PATCH, permission requirements, and start_time validation. Annotations only provide basic hints (readOnlyHint false, idempotentHint false), so the description carries the full burden and excels.

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

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

The description is long but appropriately structured: purpose first, then usage, return shape, pitfalls, and cross-references. Every sentence provides necessary context for a tool with 15 parameters and multiple upstream quirks. No fluff or redundancy; it earns its length.

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

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

Despite an output schema existing, the description still explains the return shape (same as get_recurring_meeting, with occurrences and template_meeting_id). It covers permissions, project module requirements, validation behavior, the draft-template workflow, timezone correction, and related tools. This is comprehensive for the complexity of the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds cross-parameter semantics by explaining that frequency and end_after combinations are validated locally, and that OpenProject's infer defaults never apply. It also clarifies that start_time must be now or future and time_zone is validated, adding value beyond the already-rich schema descriptions.

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

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

The description clearly states the tool's purpose: 'Create a recurring meeting series: a schedule plus a template the occurrences copy.' This goes beyond a generic 'create' verb, specifying the resource (recurring meeting series) and distinguishing it from single-meeting tools like create_meeting 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 explicitly says 'Use it for "set up a weekly sync Mondays at 9" style requests,' and provides cross-references to related tools for different steps (e.g., get_recurring_meeting, update_meeting, init_recurring_meeting_occurrence, list_projects). This gives clear when-to-use and alternative context.

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

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

The description discloses significant behavioral details beyond the annotations: POST /versions/form validation with 'violations' naming attributes, the returned object and id usage, the end_date-to-endDate mapping (and the older client dropping it silently), the 'manage versions' permission requirement, and the per-project sharing semantics. This is rich, non-obvious context.

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

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

The description is structured with clear paragraphs: primary use, when-to-use, validation behavior, return value, pitfalls, and cross-references. Every sentence earns its place, and no information is wasted. It is appropriately sized for a tool with 7 parameters and subtle behavioral caveats.

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

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

Given the tool's complexity, the description is complete: it covers creation purpose, validation behavior, return value, permission requirements, pitfalls, and relationships to sibling tools. The output schema is also present, further reducing ambiguity. This is a comprehensive and self-sufficient description.

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

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

The schema already covers all parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds extra meaning around key parameters: end_date 'always lands' and maps to the API's endDate, project_id is the defining project that cannot be changed afterwards, and the returned id is consumed by update_work_package(version=...) and update_version. These nuances go beyond the schema.

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

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

The description opens with 'Create a version (release, milestone or sprint) inside a project,' which uses a specific verb and resource, and clearly distinguishes this tool from sibling tools like update_version, list_versions, and delete_version.

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

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

The description explicitly states when to use the tool ('Use it to open a new sprint or plan a release before assigning work packages to it') and provides cross-references to alternatives: list_versions for existing versions, update_version for changes, and list_projects for project id. This gives clear guidance on when to use this tool vs 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, etc.), the description discloses the form-validation pre-flight, structured error responses with allowed values, return details (id, lock_version, resolved custom fields), and pitfalls around parameter types (names vs numeric ids) and milestone date restrictions. This is rich, non-obvious behavioral context.

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

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

The description is tightly organized: purpose, use cases, validation behavior, return value, pitfalls, and alternatives. Every sentence provides actionable information. It is longer than average, but the density of useful detail justifies the length.

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 (17 parameters, output schema present, rich annotations), the description covers everything an agent needs: what it does, how validation works, what is returned, key parameter restrictions, and where to get more schema details. It also names sibling tools for follow-up actions, making the description contextually complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value through synthesized pitfalls: 'type, status and priority take names or ids, but versions, assignees and parents need numeric ids' and 'Milestone types reject start_date/due_date — use date.' These cross-cutting rules go beyond individual schema descriptions but are not huge; hence 4.

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

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

The description opens with 'Create a work package' — a specific verb and resource. It further clarifies scope by listing use cases: new tasks, bugs, subtasks (parent_id), and milestones (date). It distinguishes from siblings by explicitly naming update_work_package and upload_attachment for post-creation actions.

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

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

The description explicitly says 'Use it for new tasks, bugs, subtasks...' and gives alternatives: 'To change it afterwards use update_work_package; to attach a file to an existing work package use upload_attachment.' It also directs users to get_work_package_schema when unsure about custom fields, providing clear when-to-use and 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?

Reveals critical server-side behaviors: canonical direction rewriting, 409 on duplicate relations, rescheduling on 'follows', and cycle rejection. This goes far beyond the annotations' basic readOnly/destructive hints and gives the agent essential insight into side effects.

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

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

Though relatively long, the description is tightly organized into purpose, return value, pitfalls, and cross-references. Key information is front-loaded in the first sentence, and every paragraph adds necessary operational context without redundancy.

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

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

Covers return shape, error conditions (409, validation errors), side effects (date rescheduling), and alternatives. With an output schema present and thorough parameter descriptions, nothing essential is missing for correct tool selection and invocation.

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

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

Schema descriptions already cover all 5 parameters thoroughly, including enum meanings and lag constraints. The description adds important nuances like direction canonicalization and the single-relation rule, which affect how parameters are interpreted and what to expect in the response.

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 'Link two work packages' and lists the relation types, making the tool's specific verb and resource unmistakable. It clearly distinguishes itself from sibling tools by focusing on creating a relation, versus updating or deleting one.

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

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

Explicitly says 'Use this to record a dependency' and provides real examples. Pitfalls state when not to use it (409 conflict, use update on existing id) and cross-references list alternatives for listing, editing, deleting relations, and for parent-child hierarchy.

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

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

Annotations already flag destructive=true, but the description goes far beyond by explaining the read-before-delete flow, 403/404 semantics, non-idempotency (second call returns 404), cascading effects on embedded content, and permission requirements. No contradiction with annotations; instead it enriches them.

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?

Structured with clear sections (main action, usage, pitfalls, related). Every sentence provides necessary information for a destructive tool; nothing is redundant or filler.

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

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

Comprehensive for a destructive attachment operation: purpose, prerequisites, error behavior, side effects, and alternatives are all covered. The presence of an output schema and 100% schema parameter coverage complements the rich description, making this a complete tool definition.

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

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

The input schema already covers both parameters well (100% coverage). The description adds valuable extra context by explaining that attachment_id must come from list_attachments or get_work_package and that an unknown id fails before deletion, supplementing the schema's warning about wrong id types.

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 'Permanently delete one attached file from OpenProject' — a specific verb, resource, and scope. It clearly distinguishes this from sibling attachment operations like list_attachments, upload_attachment, and download_attachment.

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

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

Provides explicit guidance: 'Use it only on explicit user instruction' with concrete use cases (remove a mis-uploaded or superseded file). The Related section names list_attachments, upload_attachment, and download_attachment as alternatives, making when-to-use crystal 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?

Beyond the annotations (destructiveHint=true, etc.), the description discloses critical behavioral details: irreversibility ('no API-side undo'), cascading deletion of agenda/outcomes/attachments, permission requirements, and specific error semantics (403 vs 404, plus OpenProject version caveat). This adds substantial context beyond what annotations alone convey.

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

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

The text is well-organized into paragraphs and bullet-like pitfalls, each sentence carrying meaningful information. It front-loads the primary purpose and irreversibility, then provides alternatives, return behavior, and error guidance without redundancy.

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

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

The description is fully complete for a destructive, annotation-rich tool. It covers safety prerequisites, alternatives, error interpretation, and cross-references to check before deletion. The presence of an output schema means return value details are not needed, and the description fills all other essential context.

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

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

Although the schema already covers 100% of parameters, the description enhances meaning for both: confirm is explained as mandatory to avoid accidental deletion with a clear consequence for false, and meeting_id is advised to be read back and shown to the user because ids are not human-readable. This goes beyond the schema's field descriptions.

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

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

The description opens with a specific verb and resource ('Permanently delete a meeting, together with its agenda and recorded outcomes'), clarifying both the action and its scope. It also distinguishes itself from sibling tools like update_meeting and get_meeting by explaining what makes this tool unique.

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

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

It explicitly states when to use the tool ('Use only on explicit user instruction') and provides a concrete reversible alternative ('update_meeting(meeting_id=..., state='cancelled')') for situations where deletion is not appropriate. Cross-references further guide selection among related meeting tools.

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

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

Beyond the destructiveHint annotation, the description discloses that outcomes are permanently removed, items shift up, the meeting is untouched, a confirmation object is returned, closed meetings reject deletion, and a 404 can have multiple causes (including OpenProject version). This is rich behavioral context that annotations alone don't 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 main action, then efficiently covers implications, pitfalls, and alternatives. Every sentence adds value, and the structured pitfalls section improves scannability without fluff.

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

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

Given the destructive nature and the existing output schema, the description covers return value, permission requirements, edge cases (closed meeting, version differences), and how to verify the target. It is fully complete for an agent to invoke correctly with minimal 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?

Although schema coverage is 100%, the description adds critical semantics: `agenda_item_id` is clarified as coming from `get_meeting` and being distinguished from meeting id, and `confirm` is explained with the exact failure mode (`confirmation_required` error) when false. This goes well beyond the schema descriptions.

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

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

The description starts with 'Permanently delete one agenda item, with any outcomes recorded against it' — a specific verb and resource. It distinguishes itself from the sibling `update_meeting_agenda_item` by stating that it removes rather than fixes, so the purpose is unambiguous.

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

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

It explicitly says 'Use only on explicit user instruction' and provides cross-references: `get_meeting` to check the id, `update_meeting_agenda_item` for fixing instead of removing. This gives clear when-to-use and alternative guidance beyond 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?

The description reveals many behavioral details beyond annotations: permission requirement, meeting state constraint (in_progress only), validation error vs 403, 404 meanings including OpenProject version nuance, confirmation behavior with confirm=false, and permanent no-undo nature. These enrich the safety profile indicated by destructiveHint.

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

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

The description is well-structured and concise, front-loading the core action, then usage, return value, pitfalls, and cross-references. Every sentence provides essential information without fluff, and formatting (paragraphs and bullets) aids 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 destructive tool, the description covers all necessary context: prerequisites (permission, meeting state), exact error semantics, confirmation requirement, and retrieval of the id. With an output schema present, the description needn't detail the return object, making it fully 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?

Despite 100% schema coverage, the description adds crucial contextual meaning: confirm must be true because the API offers no undo, and outcome_id should come from get_meeting after checking the text. It explains error responses tied to parameters, surpassing baseline.

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

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

The description opens with a specific verb and resource: 'Permanently delete a recorded outcome from a running meeting's minutes.' It clearly distinguishes the tool from siblings like update_meeting_outcome by emphasizing irreversible deletion versus correction.

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

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

Explicit usage guidance is provided: 'Use only on explicit user instruction, for an outcome recorded by mistake or against the wrong item.' It also names the alternative for wrong text and cross-references get_meeting for verification, leaving no ambiguity about when to use.

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

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

Despite the destructiveHint annotation already flagging danger, the description adds critical behavioral details: the entry and all comments are removed permanently, API v3 offers no undo or trash, the 'manage news' permission is required, and 403 vs 404 error meanings are explained. This goes well beyond the annotation.

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

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

The description is well-organized with a clear lead sentence, usage context, return value, pitfalls, and cross-references. Every sentence adds value and there is no redundant fluff—the length is justified by the density of 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?

Given the destructive nature and availability of an output schema, the description covers all essential context: when to use, what happens (permanent deletion, comments removed), permission requirements, error interpretation, and related sibling tools. It is complete for a responsible AI agent to invoke safely.

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

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

The input schema already provides thorough descriptions for both parameters (confirm must be true, news_id should be read back from get_news), achieving 100% coverage. The description itself adds no additional param-specific meaning beyond the schema, so it matches the baseline for high schema coverage.

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

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

The description begins with a clear, specific verb and resource: 'Permanently delete a news entry.' It also distinguishes the tool from its sibling update_news, explicitly positioning delete_news as the irreversible action for mistaken or wrong-project announcements.

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

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

The description provides explicit when-to-use guidance: use for an announcement 'published by mistake or in the wrong project.' It names the alternative, update_news, for outdated but real announcements, and cross-references list_news/get_news for retrieving the id and can_manage permissions.

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 substantial context: cascading deletion of all sub-objects, asynchronous background execution, the scheduled-return contract, admin rights requirement, 404 semantics, and the possibility of invisible background failures. This goes far beyond the annotations.

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

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

Though long, the description is tightly structured with clear sections: primary action, usage warning, cascade effect, alternative, async behavior, pitfalls, and cross-references. Every sentence provides actionable information, and the front-loaded summary ensures the core purpose is immediately visible.

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, asynchronous, cascading deletion tool, the description covers all essential aspects: what gets deleted, how to verify, error conditions, failure visibility, and cross-references to related tools. The presence of an output schema reduces the need to explain return values, but the description still covers the scheduling aspect.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces the schema by emphasizing the confirm requirement and advising to read back the project before passing id_or_identifier, adding practical guidance that helps avoid typos. This exceeds the baseline of 3.

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

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

The description opens with a specific verb+resource: 'Schedule the permanent deletion of a project and everything inside it.' It clearly distinguishes this from sibling tools like delete_work_package and update_project by emphasizing the cascading, destructive scope.

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

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

Explicitly states when to use ('Use only on an explicit, specific instruction') and provides a concrete reversible alternative: update_project(active=false) for archiving. Also mentions prerequisites (admin rights) and what to do in error cases, giving clear situational guidance.

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

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

Even though annotations already declare destructiveHint=true, the description adds critical behavioral context: past minutes are destroyed, participants are emailed cancellations when notify is set, permission requirements (403 indicates account problem), 404 has three possible meanings including OpenProject version limits, and the return is a confirmation object. It also explains the confirm parameter's role in preventing accidental deletion.

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

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

The description is dense but every sentence adds value: primary purpose, usage guardrail, return value, pitfalls, cross-references. It is well-structured with clear paragraph breaks (Pitfalls, Cross-references) and front-loads the most critical information. No fluff or redundancy.

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

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

Given this is a destructive, complex operation with an output schema, the description provides comprehensive context: permission errors, version compatibility, how to confirm scope, alternative tools, and what the return object is. It leaves no obvious gap for an agent to misuse the tool.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (confirm must be true, recurring_meeting_id from list_recurring_meetings). The description adds complementary context by reinforcing that the ID refers to the whole series and advising to read it back with get_recurring_meeting and show the user the title. It doesn't repeat schema details but enriches them with operational 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 clearly states it permanently deletes a recurring series (template, schedule, and EVERY occurrence), which is a specific action on a specific resource. It also distinguishes itself from sibling tools like cancel_recurring_meeting_occurrence and delete_meeting, eliminating ambiguity about scope.

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

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

Explicit guidance is provided: 'Use only on explicit user instruction, and make sure the user means the whole series'. It names exact alternatives for dropping a single slot or a single instantiated meeting, and cross-references get_recurring_meeting for pre-checking. This is textbook when-to-use/when-not-to-use clarity.

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 significant context beyond annotations: deletion 'removes the booked hours from every cost report and from the work package's aggregated spent time, with no API-side undo.' Also discloses permission requirements, failure mode (permission_denied), and closed-period limitations.

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

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

Front-loaded with the main purpose, then organized into usage, behavior, pitfalls, and cross-references. Every sentence carries necessary safety or usage 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 destructive tool with a confirmation flag, this description covers when to use, how to confirm, side effects, failure modes, and alternatives. Output schema exists, so return format doesn't need explanation. Fully equips the agent for safe invocation.

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

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

Schema already covers both parameters at 100%, but description enriches their meaning: explains confirm must be true, the confirmation_required error when false, and that time_entry_id comes from list_time_entries and must be checked before calling. This adds practical workflow context beyond 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?

Description opens with 'Permanently delete a logged time entry' — a specific verb and resource. It explicitly distinguishes itself from update_time_entry and list_time_entries through cross-references, making it unambiguous which tool to use.

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

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

Provides explicit when-to-use guidance: 'Use only on explicit user instruction, and only for genuinely wrong entries.' Names update_time_entry as the better alternative for wrong day/duration/activity and notes permission and closed-period 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?

Discloses key behaviors beyond annotations: work packages are NOT deleted, 422 refusal on referenced versions, 403 permission requirement, and shared version impact. This goes well beyond the destructiveHint annotation and adds context that affects the agent's decision-making.

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

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

The description is long but well-structured with separate paragraphs for usage guidance, side effects, and pitfalls. Each sentence carries useful information, though a few could be merged. It earns a 4 for density without redundancy.

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

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

Covers prerequisites (list_versions), alternatives (update_version), side effects (shared versions, work packages), error scenarios (422, 403), and confirmation flow. With an output schema present, no need to describe return values. Complete 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 100% with detailed descriptions for both params (confirm must be true, version_id numeric and from list_versions). The description reinforces these points (e.g., 'Ask the user first') but adds little beyond schema. Baseline 3 is appropriate.

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

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

The description states 'Permanently delete a version' with a specific verb and resource, clearly distinguishing it from the reversible alternative update_version(status='closed'). It also clarifies the scope (work packages are not deleted, only lose their version).

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

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

Explicitly states when to use ('only for a version created by mistake') and when not to (for a finished release or sprint, use update_version(status='closed')). Cross-references list_versions and list_work_packages for prerequisites and pre-removal checks.

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, but the description adds substantial context: deletion is permanent, removes comments/attachments/time entries/relations, has no API-side undo, and the key pitfall that children are not deleted. It also clarifies the return behavior with a confirmation object.

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

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

The description is well-structured with a clear purpose, warning, return note, and pitfalls section. Every sentence carries important operational information, with no filler or redundancy.

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

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

Given the tool's destructive nature and the presence of an output schema, the description covers all critical aspects: prerequisites (check children), cascading deletion effects, alternatives, the confirm flag behavior, and the permanent consequences. It is fully sufficient for an agent to invoke this tool safely.

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 input schema already provides detailed descriptions for both parameters, including the confirm flag's requirement and behavior. The description reinforces the confirmation requirement but does not add new parameter-level details beyond what the schema provides.

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

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

The description opens with a clear, specific statement: 'Permanently delete a work package and everything attached to it.' This names the exact action and resource, and distinguishes the tool from related siblings like delete_work_package_relation and 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?

The description gives explicit when-to-use instructions: 'Use only on explicit user instruction.' It also advises checking children via get_work_package before deletion and recommends update_work_package with a closed status as a safer alternative, referencing get_project_metadata for closed statuses.

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 destructiveHint and non-idempotent annotations, the description adds crucial context: deleting a 'follows' relation may trigger rescheduling, there is no undo, and a second delete returns 404. It also explains the confirm parameter's role in avoiding accidental deletion. This goes well beyond what annotations alone convey.

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

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

The description is well-structured with a clear lead, a 'Pitfalls' section, and cross-references. Each sentence earns its place, and it is succinct despite covering multiple nuances. It is neither under-specified nor bloated.

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 destructive nature of the tool, the description covers all critical aspects: side effects, non-reversibility, idempotency behavior, and alternative tools. With an output schema present, return values need not be described. The description is complete for an agent to invoke this tool safely and correctly.

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

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

The input schema already provides 100% parameter coverage, including the confirm requirement and the source of relation_id. The description itself adds almost no new parameter-level detail, so the baseline of 3 is appropriate. The mention of confirm=false behavior in the description is redundant with the schema.

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

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

The description opens with a clear, specific action: 'Remove the link between two work packages.' It goes on to distinguish this from sibling tools like update_work_package_relation and delete_work_package, and clarifies that parent/child hierarchy is not a relation. This makes the tool's exact scope immediately obvious.

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

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

The description explicitly states when to use it ('Use it when a dependency no longer holds') and provides concrete alternatives: 'update_work_package_relation changes a relation instead of removing it' and 'clear it with update_work_package(parent_id=null)' for hierarchy. This gives the agent clear decision criteria.

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

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

Annotations only hint at read-only and non-destructive intent, but the description explains actual behavior: streaming to disk with progress, return fields including SHA-256, local-vs-server path caveat, quarantine and virus-scan failures, size limits with mid-stream aborts, and name-collision handling. This far exceeds annotation coverage.

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

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

The description is long but every sentence earns its place. It is structured with a clear lead, workflow, return-value summary, pitfalls, and related tools, making it scannable and information-dense without redundancy.

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

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

Covers the full lifecycle: prerequisites, execution behavior, return values, error conditions, size limits, filename conflicts, and deployment context. For a tool with this complexity and an output schema, the description is complete and self-contained.

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?

Even though schema coverage is 100%, the description adds critical nuances: attachment_id is explicitly 'Not a work package id', save_dir defaults and relative-path rejection rationale, and return_image's 1 MB/type limitations. This adds real semantic value beyond the schema.

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

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

The description opens with 'Download an attachment's bytes to a file on the machine running this server,' which uses a specific verb and resource, clearly distinguishing it from sibling tools like upload_attachment, list_attachments, and delete_attachment. It also references related tools, reinforcing its unique role.

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

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

Explicitly states when to use ('Use it once list_attachments (or get_work_package(include=["attachments"])) has given you an attachment_id') and provides prerequisites. It also covers when not to use (quarantined, unfinished virus scan, oversized files) and names the reverse operation (upload_attachment).

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, the description discloses that only comment entries are editable, field-change entries are rejected locally before any write, editing requires specific permissions, the text is replaced entirely with no API-visible history, editing does not notify anyone, and the return shape matches list_work_package_comments. No contradictions with annotations.

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

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

Though lengthy, every sentence earns its place: purpose, use cases, return shape, pitfalls, permissions, irreversibility, and cross-references. The description is front-loaded with the primary action and well-structured with paragraph breaks for 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?

The description is exhaustive given the tool's complexity: covers prerequisites, error handling (403), non-comment journal entries, side effects (no notifications, no history), and explicitly names sibling tools. An output schema exists, so return values require no further explanation.

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 detailed descriptions for both parameters (comment, activity_id). The tool description adds little beyond the schema: 'replaces text entirely' and 'activity id' already appear in the schema. The baseline of 3 applies because structured data carries the semantic load.

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

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

The description opens with 'Rewrite the text of an existing work-package comment,' a specific verb+resource statement. It further clarifies use cases (fix a typo, correct a wrong statement, extend a note) and differentiates from add_work_package_comment and update_work_package via cross-references.

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

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

Explicitly states when to use ('Use this to fix a typo...'), when not to use ('do not use it to "undo"'), and names specific alternatives (list_work_package_comments, add_work_package_comment, update_work_package). It also explains the permission requirements and 403 implication.

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 (readOnlyHint=false, destructiveHint=false), the description reveals critical behavioral traits: the action determines changes and does not report which fields it touched, availability varies per work package (403/422 errors), writes are never auto-retried, and conflicts return a fresh lock_version. This adds substantial context beyond the structured metadata and matches the annotations (no contradiction).

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

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

The description is moderately long but every sentence carries weight: it defines the tool, gives examples, explains pitfalls, and offers cross-references. It is front-loaded with the core behavior and then organized into a clear pitfalls section, making it scannable and dense without redundancy.

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

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

With an output schema present, the description still adds essential context: it summarizes what the return row contains, explains error conditions (403, 422), concurrency behavior, and how to recover from conflicts. It also references related tools for obtaining IDs and reading journal entries, making it complete for an agent to safely execute the action in real scenarios.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for custom_action_id ('never guess an id', tells where to get it) and reinforces lock_version behavior, going beyond the schema's descriptions. It doesn't add much for work_package_id but the schema already covers it adequately. Thus a 4 is justified.

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

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

The description uses a specific verb ('Run') and names the resource ('instance-defined one-click action on a work package'), immediately clarifying what the tool executes. It also distinguishes itself from update_work_package and get_work_package by referencing them as alternatives, so the agent can tell them apart.

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

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

It explicitly says when to use the tool: 'Use one when get_work_package(include=['custom_actions']) offers it, instead of reproducing its effects field by field.' It also names the alternative tools (update_work_package, get_work_package) and explains when those are preferred, giving clear usage boundaries.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description discloses that attachments are not part of the result, that description can be empty for block editor content, and that editing is unsupported. These are significant behavioral traits that the agent would not know from annotations alone.

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

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

The description is compact yet information-dense, with clear paragraphs for purpose, usage, pitfalls, and cross-references. Every sentence earns its place, and the use of 'Pitfalls' makes unusual behaviors easy to spot. No fluff or redundancy.

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

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

For a simple read operation with one parameter and an output schema, the description covers all critical aspects: what is returned, what is not returned (attachments), potential empty description, and related tools. The existence of an output schema means return format details are already external, so the description is fully complete.

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

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

The only parameter document_id is fully described in the input schema, including its origin ('from list_documents') and format. The description reinforces this by cross-referencing list_documents for the id, but does not add meaning beyond what the schema already provides. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description opens with 'Read one document with its full description text', which is a specific verb and resource. It clearly differentiates from siblings like list_documents (listing all) and download_attachment (files) by focusing on a single document's description text.

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

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

The description explicitly states 'Use it after `list_documents` when the title is not enough', providing a clear when-to-use condition. It also names alternatives for attachments (list_attachments) and files (download_attachment), and notes that editing is unsupported, giving complete guidance on when not to use it.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description explains critical behavioral nuances: the record is a mirror refreshed via webhooks so `updated_at` is sync time, not GitHub change time; a 404 commonly indicates a wrong id or missing GitHub module; and PRs appear only when they mention 'OP#123' or the full work-package URL, with no API-based link creation. This adds substantial context to annotation-provided hints.

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

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

Although lengthy, the description is well-structured with clear paragraphs: main purpose, usage context, pitfalls, data-appearance conditions, and cross-references. Each sentence contributes meaningful information; there is no filler or repetition beyond acceptable reinforcement. The use of 'Pitfalls.' and 'Cross-references:' headers improves scannability.

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 (external data mirror, non-obvious id semantics, linkage constraints), the description is complete. It covers usage flow, error interpretation, data freshness, privacy of linkage, and alternatives. The output schema already documents return values, so the description focuses on behavioral and contextual aspects, making it fully adequate.

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

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

The schema already has 100% coverage with a rich description clearly distinguishing `github_pull_request_id` from the GitHub number. The description reinforces this with the pitfall statement ('never the GitHub number… no lookup by GitHub number') and adds a diagnostic hint ('404 usually means the id came from the wrong field or the GitHub module is not installed'). While mostly redundant with the schema, the added 404 context nudges it above the 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?

The description starts with a specific verb and resource: 'Read one linked GitHub pull request in full, including its CI check runs.' It clearly distinguishes this tool from the sibling `get_work_package_git_activity` by specifying that this provides full PR details while the sibling returns a summary. The scope is unambiguous and the resource is precisely identified.

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

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

Explicit guidance is given: 'Use it after get_work_package_git_activity when the summary is not enough.' It also documents when not to use it for GitLab merge requests, stating they 'have no per-id tool — they come back in full from that same call.' Cross-references show exactly how to find the id, satisfying the guideline requirement thoroughly.

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

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

Despite annotations already indicating read-only, idempotent, and non-destructive behavior, the description adds significant behavioral nuance: it authenticates on every call rather than caching, describes what 'features' represents (server version vs user permissions), and explains error semantics (401 vs network error) with actionable hints. This goes beyond the annotations.

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

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

The description is well-structured: it opens with a clear purpose, then provides usage triggers, a concise list of return values, pitfalls, and alternatives. Each sentence adds unique value. Despite its length, it is tightly written and front-loaded with the most 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?

Although the tool has no parameters and a rich output schema, the description fully explains when to use it, what it returns, why it should be called first, how to interpret failures, and how it differs from related tools. There is no gap in context for an agent to infer 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?

The tool has zero parameters, so there is nothing for the description to explain about parameters. The schema coverage is trivially 100%. The description does add substantial value by detailing the return fields (version, name, attachment size, user info, features), which compensates for the lack of parameter-level semantics. The score is a baseline 4 because with no parameters, the description cannot earn full marks in this dimension.

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

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

The description clearly states the tool's purpose: "Check the OpenProject connection and report what this instance supports." It uses specific verbs (check, report) and a specific resource (instance info). It also distinguishes itself from sibling tools by explicitly pointing to get_project_metadata and list_permissions for related but different information.

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

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

Provides explicit when-to-use guidance: "Call this first when anything fails in an unexplained way, when the user asks 'am I connected / who am I', or before using a version-gated parameter." It also names alternatives for per-project metadata and user permissions, making the usage context crystal 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?

Beyond the annotations (readOnly, idempotent, etc.), the description adds rich behavioral detail: status value lifecycle, derived fields, the meaning of a 200 response, polling requirements, job status expiration, 404 interpretation, failure message behavior, and lack of retry API. This goes far beyond what annotations alone convey.

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

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

The description is long but every sentence earns its place: purpose, background, return format, pitfalls, and cross-references are clearly segmented. It is front-loaded with the core purpose and structured for quick scanning despite its length.

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

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

For a single-parameter polling tool, the description is exceptionally complete: it covers return fields, all possible statuses, edge cases (404, successful null), polling best practices, and verification alternatives. The presence of an output schema means return details need not be fully restated, but the description still provides them, ensuring no 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 input schema's description for job_id already covers its provenance (uuid from copy_project/delete_project) and distinction from project id. The tool description reinforces this but adds no new parameter-specific semantics beyond usage context, so the baseline 3 for high schema coverage (100%) applies.

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

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

The description opens with a specific verb and resource: 'Check whether a background job (a project copy, a scheduled deletion) has finished.' It clearly distinguishes itself from siblings by stating it is the 'only way' to learn what happened to a job, and cross-references copy_project and delete_project as producers of the job_id.

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

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

Explicit when-to-use guidance is provided: 'call it after copy_project or delete_project and wait for a terminal state before reporting an outcome.' It also names alternatives for verification (get_project / list_projects) and warns about the 404 ambiguity, giving clear context on how to interpret results.

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