Server Quality Checklist

Tool Scores

• delete_versionA
  4.6/5.0
  Behavior5/5

  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.

  Conciseness4/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• get_meetingA
  4.6/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses important edge-case behaviors: empty title for work-package agenda items, null work_package when invisible, and the distinction between an empty agenda vs. an unreadable one (agenda_items empty with explanation). It also states API v3 limitations, adding significant transparency.

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

  Conciseness4/5

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

  The description is longer than typical but well-structured: it starts with the core purpose, then details return fields, then pitfalls, then cross-references. Every section provides value, especially the subtle edge cases. However, the enumeration of return fields may be redundant given the output schema exists, and the prose is dense. Still, it earns its length, so 4.

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

  Completeness5/5

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

  Given the tool's complexity (meeting data with agenda items, outcomes, visibility nuances) and the presence of an output schema, the description is remarkably complete. It covers return values, edge cases (empty title, invisible work packages, unreadable agendas), API limitations, and related tools, leaving no obvious gaps 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.

  Parameters3/5

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

  The input schema already fully describes meeting_id (numeric id from list_meetings, not a project or agenda item id), so schema coverage is 100%. The description adds the cross-reference 'list_meetings for the id' and the note about lock_version for update_meeting, but it does not add new semantics for the parameter beyond what the schema provides. At baseline, a 3 is appropriate.

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

  Purpose5/5

  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: 'Read one meeting in full: participants, the agenda, and any recorded outcomes.' It clearly distinguishes the tool from siblings by naming alternatives in cross-references (add_meeting_agenda_item, list_meetings, update_meeting, delete_meeting), making its purpose unambiguous.

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

  Usage Guidelines5/5

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

  The description provides explicit usage context ('This is the "what was discussed / what was decided" call') and gives alternatives with clear purposes: 'list_meetings for the id', 'update_meeting / delete_meeting change or remove the meeting itself.' It also notes what is NOT exposed (attendance, minutes, section titles), helping the agent decide when not to use this tool.

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

• get_userA
  4.6/5.0
  Behavior5/5

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

  The description adds significant context beyond annotations: visibility-dependent nulls, the deliberate dropping of avatar URL, 404 behavior for group/placeholder ids, and the meaning of 'me'. No contradiction with readOnlyHint=true or other annotations.

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

  Conciseness4/5

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

  The description is thorough and organized with a clear opening, a usage paragraph, a return-value line, a pitfalls section, and cross-references. It is longer than necessary but every sentence adds value; front-loaded with the core purpose.

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

  Completeness5/5

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

  The description is complete for a simple read tool: it covers what fields are returned, visibility caveats, error behavior (404), idempotency context, and direct alternatives. The presence of an output schema and supportive annotations further reduces ambiguity.

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

  Parameters3/5

  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 reinforces the parameter's dual type (integer or 'me') and mentions the restriction on group ids, but the schema already captures these details. No substantial additional parameter semantics are provided.

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

  Purpose5/5

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

  The description opens with a specific verb+resource ('Read one user's profile') and lists concrete fields (name, login, email, admin flag, status). It clearly distinguishes itself from siblings by referencing search_principals (which returns only names) and list_permissions (for project permissions).

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

  Usage Guidelines5/5

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

  Explicit usage guidance is provided: 'Use it after search_principals when you need more than a name' with concrete scenarios (confirm active account, check admin, use 'me'). It also gives an exclusion ('admin=true says nothing about project permissions; use list_permissions') and cross-references other tools.

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

• init_recurring_meeting_occurrenceA
  4.6/5.0
  Behavior5/5

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

  Beyond the annotations (idempotentHint, openWorldHint), the description discloses critical behaviors: idempotent return of an existing open meeting, restoration of cancelled occurrences, permission requirements, HTTP 500 for draft templates, and the non-validation of the instant leading to off-schedule meetings. 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.

  Conciseness4/5

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

  The description is lengthy but every section earns its place: purpose, usage, return shape, pitfalls, permissions, and cross-references. It is well-structured with clear paragraphs and bullet-like pitfall sections, though slightly verbose; could be tightened without losing critical content.

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

  Completeness5/5

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

  Given the tool's complexity and the existence of an output schema, the description provides comprehensive context: it explains the returned meeting shape references get_meeting, covers error modes (wrong instant, draft template), permission issues, and cross-references sibling tools. The agent has everything needed to invoke correctly and avoid known pitfalls.

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

  Parameters3/5

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

  The schema already has 100% coverage with detailed descriptions for both parameters, including the verbatim copy warning for start_time and the distinction between series id and meeting id. The main description repeats these points but adds no new parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description opens with a specific verb+resource+outcome: 'Materialize one occurrence of a series as a real meeting, copied from the template.' It clearly differentiates this tool from its siblings (e.g., cancel_recurring_meeting_occurrence) by explaining the occurrence becomes a normal meeting that other meeting tools can operate on.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use it ('when a specific slot needs its own agenda, minutes or attachments before the day'), describes behavior on cancelled vs. existing occurrences, and points to alternatives like get_recurring_meeting for exact start_time strings and update_meeting for follow-up changes. It also warns against misuse with specific pitfall examples.

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

• remove_work_package_watcherA
  4.6/5.0
  Behavior5/5

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

  The description goes far beyond annotations by disclosing critical behavioral nuances: the API returns 204 regardless of whether the user was actually watching, resulting in 'changed' being null; a 404 indicates an unknown user or work package, not non-membership; and the operation does not unassign or remove from project. These are exactly the kind of hidden behaviors agents need, and they complement the idempotentHint and destructiveHint annotations 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.

  Conciseness4/5

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

  The description is longer than necessary but earns its length through crucial pitfalls and permission details. It is well-structured with a clear 'Pitfalls' section that is immediately relevant to safe execution. No sentence is wasted, though a more compressed format could have achieved the same impact.

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

  Completeness5/5

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

  For a mutation tool with subtle API behaviors, the description covers all essential context: operation, return value (though output schema exists), permission requirements, error semantics, and cross-references to related tools. The presence of an output schema does not detract; the description adds the non-obvious 'changed is null' detail that the output schema alone would not convey.

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

  Parameters3/5

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

  The input schema already provides 100% coverage of both parameters, including how to obtain IDs and the rejection of 'me' for user_id. The description adds no new parameter-level meaning beyond what the schema states; it merely restates and contextualizes. Per the rubric, baseline 3 is appropriate when schema does the heavy lifting.

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

  Purpose5/5

  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: 'Unsubscribe a user from a work package's notifications.' This clearly distinguishes it from siblings like add_work_package_watcher and get_work_package, and the cross-reference to add_work_package_watcher as the reverse further cements its unique purpose.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use this tool ('Use this to stop notifying someone who no longer needs the updates'), provides permission prerequisites (removing others requires delete-work-package-watchers permission, self-removal requires view access), and names alternatives (get_work_package with include=['watchers'] for listing current watchers, add_work_package_watcher as the reverse). This fully covers usage context and exclusions.

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

• add_meeting_agenda_itemA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• delete_newsA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• delete_work_packageA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• delete_work_package_relationA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• edit_work_package_commentA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• get_documentA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• get_job_statusA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• get_newsA
  4.7/5.0
  Behavior5/5

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

  The description discloses several behavioral traits beyond the readOnlyHint annotation: it returns specific fields, 'author' cannot be changed, 'can_manage' indicates edit/delete permission, HTML is dropped, and comments are not exposed. This provides rich context not available 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.

  Conciseness5/5

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

  The description is longer than average but well-structured: it opens with the core purpose, then covers return value, pitfalls, and cross-references. Every sentence adds valuable information, and the front-loading makes it easy to scan.

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

  Completeness5/5

  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, the description is complete. It covers return fields, permission hints, error semantics, and exclusions. Since an output schema exists, the description need not explain return values in detail, but it does so anyway, making it self-sufficient.

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

  Parameters3/5

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

  The schema already fully describes the only parameter news_id, including its numeric type and source from list_news. The description reinforces this by saying 'list_news produces the id' but adds no new semantic meaning beyond the schema, so a baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description starts with 'Read one news entry in full, including the markdown body,' which clearly states the action and resource. It also distinguishes from siblings by noting it is used after list_news and that update_news/delete_news are cross-references.

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

  Usage Guidelines5/5

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

  Explicitly states when to use: 'Use it after list_news when the summary is not enough.' It also provides alternatives (update_news, delete_news) and includes a pitfall about 404 semantics, which helps avoid misuse.

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

• get_projectA
  4.7/5.0
  Behavior5/5

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

  The annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is known. The description adds valuable behavioral details: the exact return fields, rich text returned as markdown raw with HTML dropped, the pitfall that an empty status_code means no status set rather than 'on track', and that a 404 indicates a wrong id/identifier or an archived/invisible project with an error hint. These go well beyond the structured annotations.

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

  Conciseness5/5

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

  The description is organized with a clear opening purpose, usage guidance, return format, pitfalls, and pointers to related tools. Each sentence provides essential information, especially the pitfalls section that prevents misinterpretation of status_code and 404 responses. It is detailed but not padded.

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

  Completeness5/5

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

  The description covers what the tool returns, how to use it, important pitfalls, and how it relates to sibling tools. With an output schema present, the description's list of return fields is redundant but adds clarity. It fully equips an agent to decide when to call this tool and what to expect.

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

  Parameters3/5

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

  Schema coverage is 100%; the schema already documents that id_or_identifier accepts either a numeric id or URL identifier, with examples and a note about slugs. The description reinforces that identifiers come from list_projects but does not add new semantic detail beyond the schema. Baseline of 3 applies.

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

  Purpose5/5

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

  The description opens with 'Read one project in full,' which clearly states the action (read) and resource (project). It distinguishes from siblings by specifying that it retrieves a single project by id or identifier, unlike list_projects which lists all projects.

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

  Usage Guidelines5/5

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

  Explicit guidance: 'Use it after list_projects when you need the description, the status explanation or the parent of a specific project — or to verify that an id or identifier a user gave you actually resolves.' It also names alternative tools for related needs: get_project_metadata for internal ids and list_work_packages for work packages.

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

• get_project_report_dataA
  4.7/5.0
  Behavior5/5

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

  Annotations only declare readOnlyHint/openWorldHint/idempotentHint, but the description adds extensive behavioral context: truncation and `truncated`/`notes` behavior, `open_by_status` being 'as of *now*', `updated` including closed rows, permission-bound time visibility degrading into `notes` entries, and the `is_closed` flag robustness on translated workflows. This far exceeds the annotation baseline.

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

  Conciseness5/5

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

  The description is well-structured with clear sections: purpose, return contents, safe classification, pitfalls, and cross-references. Though long, every sentence conveys critical edge-case or usage information – it is dense but not bloated, and the key purpose is front-loaded.

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

  Completeness5/5

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

  Given the tool's complexity (multiple return buckets, truncation, permission-dependent fields, server-side computed counts), the description covers all major aspects: return structure, pitfalls, degradation behavior, and drill-down alternatives. The presence of an output schema further completes return-value understanding, so the description is fully adequate.

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

  Parameters3/5

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

  Schema description coverage is 100% with detailed parameter descriptions (e.g., from_date explains inclusive ISO and that it's never inferred). The description does not add per-parameter semantics beyond the schema; it focuses on usage and return behavior. Per rubric, baseline 3 applies when schema fully documents parameters.

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

  Purpose5/5

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

  Description opens with 'Aggregate everything a status report needs about one project and one date window' – a specific verb, resource, and scope. It distinguishes from sibling listing tools by saying 'one call replaces a dozen filtered listings' and enumerates exactly what it returns (buckets, counts, time summary, roster).

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

  Usage Guidelines5/5

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

  Explicitly states 'Use it for weekly reports, sprint reviews, standups and "what happened in June"' and provides clear alternatives for drill-down: 'drill into a bucket with list_work_packages, into hours with list_time_entries, and into one row with get_work_package.' This gives both when-to-use and when-to-use-alternatives.

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

• get_recurring_meetingA
  4.7/5.0
  Behavior5/5

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

  Annotations already mark it read-only and non-destructive, but the description adds significant behavioral detail: occurrences are capped with a `notes` field indicating when the cap was hit, template edits go through regular meeting tools, draft templates block initialization, and a 404 can mean four different things including API version compatibility. 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.

  Conciseness5/5

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

  The description is long but every sentence has purpose. It is front-loaded with a one-line summary, then structured into use-case, return format, pitfalls, and cross-references. Formatting with code spans and paragraph breaks improves scannability without wasting words.

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

  Completeness5/5

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

  For a read tool with one parameter, an output schema, and good annotations, the description fully covers return fields, occurrence state semantics, the cap pitfall, template behavior, and error interpretation. It also positions the tool within the broader toolset, making it complete for an agent to select and invoke correctly.

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

  Parameters3/5

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

  Schema coverage is 100% — the parameter `recurring_meeting_id` is already described as 'Numeric series id from list_recurring_meetings. Never a meeting id'. The description reinforces this by saying to use `list_recurring_meetings` for the series id, but doesn't add substantially new parameter-specific meaning beyond the schema.

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

  Purpose5/5

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

  The description opens with 'Read one recurring series in full: the schedule plus its next occurrences,' which clearly states a specific verb (read) and resource (recurring series). It distinguishes from siblings like list_recurring_meetings (listing all series), init/cancel occurrence (modifying a single slot), and delete_recurring_meeting (removing the whole series).

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

  Usage Guidelines5/5

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

  It explicitly frames this as 'the step before touching any occurrence' and explains how the returned `start_time` and `meeting_id` feed into other tools. Cross-references name exact alternatives: `list_recurring_meetings` for the series id, `init_recurring_meeting_occurrence` / `cancel_recurring_meeting_occurrence` for a slot, `update_meeting` on the template, and `delete_recurring_meeting` for the whole series. This is 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.

• get_wiki_pageA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial context beyond these: no wiki index or search, content not exposed by the API, 404 meaning an invalid id or disabled wiki, and no sub-pages or revisions. These details are critical and not derivable from annotations.

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

  Conciseness5/5

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

  The description is well-structured with a clear opening statement, logical sections for limits, use cases, and pitfalls, and no redundant sentences. Every detail earns its place, and the length is justified by the tool's unusual constraints.

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

  Completeness5/5

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

  The description fully covers the tool's context: what it returns, what it cannot do, how to handle errors, and related tools. Given that an output schema exists (indicated by context), the lack of explicit return-type explanation is not a gap. This is complete for the tool's complexity.

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

  Parameters3/5

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

  The schema provides 100% coverage with a detailed description of wiki_page_id, including its source (page URL) and a warning to never guess it. The tool description reiterates this information without adding new parameter-level semantics, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description opens with a precise verb and resource: 'Read a wiki page's identity and project — NOT its content.' It explicitly distinguishes the tool's scope from content retrieval and clarifies the response shape. This clearly differentiates it from sibling tools that handle attachments or work packages.

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

  Usage Guidelines5/5

  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 confirm which page a URL points at, to get the project a page belongs to, and as the step before fetching its files.' It also provides an explicit alternative for reading content: 'ask the user to paste it or open the page in the browser.' Cross-references to list_attachments and get_project_metadata further guide tool selection.

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

• get_work_packageA
  4.7/5.0
  Behavior5/5

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

  The description discloses rich behavioral details beyond the readOnlyHint/idempotentHint annotations: the return shape, includes cap at 20, truncation via more_via, sub-resource degradation into notes on 403/404, and lock_version semantics for concurrent edits. 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.

  Conciseness5/5

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

  The description is longer than typical but every paragraph serves a distinct purpose: usage context, return format, pitfalls, and alternative tools. It is front-loaded with the core purpose and contains no redundant filler.

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

  Completeness5/5

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

  The description covers usage triggers, return values, edge cases, and related tools. Combined with the fully described input schema and annotations, it gives an agent everything needed to invoke the tool correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, with both id and include already fully documented in the input schema. The tool description adds little parameter-specific meaning beyond repeating the includes cap, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states 'Read one work package in full' with specific content areas, and it distinguishes itself from siblings by noting it is 'the only way to read a work package's description text'. It also explicitly references related tools for other concerns.

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

  Usage Guidelines5/5

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

  It explicitly says when to use the tool: 'This is the tool to call once a search or list has given you an id'. It also provides direct alternatives: 'For the comment thread use list_work_package_comments; for attachment bytes use download_attachment; for linked PRs and commits use get_work_package_git_activity'.

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

• list_budgetsA
  4.7/5.0
  Behavior5/5

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

  Beyond annotations, the description discloses critical behavior: the API returns no amounts, budgets are a module with silent failures (404/403 appear as successful empty lists), and the collection is fetched in full. This goes well beyond the readOnly/idempotent hints and prevents misleading financial inferences.

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

  Conciseness5/5

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

  The description is organized into purposeful paragraphs: what it does, how to use it, return format, pitfalls, and cross-references. No redundancy; every sentence contributes unique value.

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

  Completeness5/5

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

  Given the tool's complexity (API limitations, module errors) and the presence of an output schema, the description fully covers return envelope, error semantics, and related tools. Nothing essential is missing.

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

  Parameters3/5

  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 does not add much beyond the schema's project_id explanation; it references list_projects but the schema already says to use that. No additional parameter semantics are provided.

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

  Purpose5/5

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

  The description opens with 'List a project's budgets — their ids and names', which is a specific verb, resource, and scope. It clearly distinguishes this tool from siblings like list_projects or list_time_entries by focusing solely on budgets.

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

  Usage Guidelines5/5

  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 ('to see whether a project tracks budgets at all and to get a budget id') and names alternatives ('get_project_report_data' / 'list_time_entries' for effort side). It also explains how 404/403 errors are represented, so the agent knows when not to treat an empty result as definitive.

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

• list_project_phase_definitionsA
  4.7/5.0
  Behavior5/5

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

  Annotations already mark readOnlyHint/idempotentHint/destructiveHint, and the description adds substantial context: the standard envelope shape, gate semantics, permission/version requirements, and 404 behavior on older instances. This goes well beyond the structured annotations without contradicting them.

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

  Conciseness5/5

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

  The description is organized into clear, purposeful sections: purpose, usage, return format/gate semantics, pitfalls, and cross-references. Every sentence adds information; no filler or repetition of annotations. Although multiple paragraphs, the complexity of the tool justifies the length.

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

  Completeness5/5

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

  Given the presence of an output schema, full annotation coverage, and only two well-described optional parameters, the description fully compensates for any gaps. It even covers edge cases (missing gates, 404 on older instances, permission requirements) and cross-tool integration, making it complete for an agent to select and invoke correctly.

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

  Parameters3/5

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

  Schema coverage is 100% and both parameters have their own descriptions, including defaults and bounds. The tool description adds no additional parameter-level semantics, so the baseline of 3 applies per the rubric.

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

  Purpose5/5

  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: 'List the instance-global phase definitions — the vocabulary of the project life cycle.' It clearly distinguishes this tool from siblings like get_project_phase by emphasizing instance-wide catalog vs. per-project phases.

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

  Usage Guidelines5/5

  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 it to learn which phases...') and references alternatives: list_projects(in_phase=...) and get_project_phase. It also identifies when not to rely on it (phase dates not exposed, catalog vs. actual project phases), providing clear selection guidance.

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

• list_queriesA
  4.7/5.0
  Behavior5/5

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

  Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the return envelope shape, null semantics for project, public/private visibility, instance-wide query IDs, and the fact that it never runs queries—so it cannot reveal result counts. This is rich behavioral context that helps the agent understand side effects and limitations.

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

  Conciseness5/5

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

  The description is well organized into purpose, usage guidance, return details, pitfalls, and cross-references. Every sentence contributes valuable information without redundancy, and the main verb and object lead the first sentence, making it front-loaded and easy to scan.

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

  Completeness5/5

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

  Given the presence of an output schema, the description still explains the envelope and important edge cases such as global queries, visibility rules, and ID scope. It also covers cross-tool relationships with run_query, list_work_packages, and list_projects, leaving no obvious gaps 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.

  Parameters3/5

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

  The input schema already provides thorough descriptions for all three parameters, including project_id's numeric requirement, default behavior, and relationship to list_projects. The description adds little parameter-level meaning beyond what the schema offers, so baseline 3 applies with 100% schema coverage.

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

  Purpose5/5

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

  The description opens with 'List the saved work-package views (queries) this user can open,' which clearly identifies the action and resource. It distinguishes itself from siblings like run_query and list_work_packages by explicitly focusing on saved definitions rather than executing or building queries.

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

  Usage Guidelines5/5

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

  It explicitly advises using this tool to discover what a team already tracks before hand-building filters, and it names alternatives: 'run one with run_query(query_id=…)', 'build an ad-hoc query instead with list_work_packages', and 'project ids come from list_projects'. This provides clear when-to-use and alternative guidance.

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

• list_recurring_meetingsA
  4.7/5.0
  Behavior5/5

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

  The description discloses several behavioral traits beyond annotations: instance-wide listing with no project filter, `duration_hours` per occurrence, and the critical pitfall that the call succeeds with empty items when the API version/module/account cannot read meetings, with the reason in `notes`. This adds substantial value beyond the readOnlyHint and destructiveHint annotations.

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

  Conciseness5/5

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

  The description is well-structured with clear sections: purpose, usage, return format, pitfalls, and cross-references. Every sentence adds information; there is no fluff. Despite its length, it remains focused and scannable.

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

  Completeness5/5

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

  Given the tool has an output schema and good annotations, the description covers all necessary context: what it lists, how to use it, return field details, important limitations (instance-wide, version/module caveats), and related tools. Nothing important is missing.

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

  Parameters3/5

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

  The schema already provides complete descriptions for both `page` and `page_size` (100% coverage), so the baseline is 3. The description adds only a general mention of the 'standard list envelope' but does not elaborate on parameter behavior beyond what the schema states.

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

  Purpose5/5

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

  The description opens with 'List recurring meeting series — the repetition rules, not the individual meetings,' which states the verb, resource, and exact scope. It explicitly distinguishes from individual meetings and references sibling tools like `list_meetings`, making the purpose unmistakable.

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

  Usage Guidelines5/5

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

  It directly tells when to use the tool: to answer 'what regular meetings do we have' and to find series IDs needed by other tools. It also explains what it does NOT include (occurrences are in `list_meetings`) and provides cross-references to related tools, giving 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.

• log_timeA
  4.7/5.0
  Behavior5/5

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

  The description goes beyond the annotations by explicitly stating 'This is not idempotent', 'time is always booked for the token owner', and that logging time does not change the work package's status, estimate, or progress. It also details the form-endpoint validation and typed error behavior, providing valuable safety context.

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

  Conciseness5/5

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

  The description is well-structured and front-loaded with the core action, followed by usage triggers, a 'Pitfalls' section, and cross-references. Although it is long, each section is purposeful, and the use of paragraphs and labels keeps it scannable without wasting words.

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

  Completeness5/5

  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, 2 required, mutation semantics), the description is remarkably complete. It covers validation and error handling, return format, ownership constraints, non-idempotence, and related tools. The output schema is also explicitly described, so an agent has all necessary context for safe invocation.

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

  Parameters3/5

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

  The input schema already has 100% description coverage for all six parameters, including required ones like hours and spent_on. The description adds some helpful examples and cross-references (e.g., 'half a day' for hours, getting activity ids from get_project_metadata), but these are pragmatic touches rather than new parameter semantics beyond what the schema already provides.

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

  Purpose5/5

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

  The description opens with a clear, specific action: 'Book time against a work package or a project.' This immediately distinguishes it from siblings like list_time_entries, update_time_entry, and delete_time_entry, which all have different verbs and targets.

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

  Usage Guidelines5/5

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

  It provides explicit trigger examples ('Use it when the user says "log 2 hours on #1234" or "book half a day to project X"') and names alternatives for related operations: get_project_metadata for allowed activities, list_time_entries for reviewing booked time, and update_time_entry/delete_time_entry for corrections.

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

• search_work_packagesA
  4.7/5.0
  Behavior5/5

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

  Discloses that search filters and does not rank, recommends narrowing with project_id, and warns that fulltext attachment matching depends on instance database configuration. It also explains the status_scope sentinel behavior, which is not visible in annotations.

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

  Conciseness5/5

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

  Four well-organized sentences front-load the purpose and usage, then cover return format, pitfalls, and alternatives without redundancy. Every sentence earns its place.

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

  Completeness5/5

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

  Covers when to use, what it returns, how to chain results, key caveats, and sibling tool differentiation. The output schema exists, so detailed return structure is not needed in the description.

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

  Parameters3/5

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

  Schema coverage is 100% and the schema already includes rich descriptions for every parameter. The description's guidance to narrow with project_id and the status_scope behavior is already present in the schema, so the description adds little beyond it.

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

  Purpose5/5

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

  The opening line 'Find work packages by text when you do not know their ids' clearly states the verb, resource, and the trigger condition, distinguishing it from list_work_packages (structured filters) and get_work_package (by id).

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

  Usage Guidelines5/5

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

  Explicitly instructs to 'Use this first whenever a user names a ticket instead of numbering it,' and names the follow-up tools to feed the id into. It also contrasts with list_work_packages for structured filters and get_work_package for full detail.

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

• update_meeting_outcomeA
  4.7/5.0
  Behavior5/5

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

  The description goes well beyond the annotations by disclosing the critical timing rule: 'this only works while the meeting state is exactly in_progress' and warns about validation errors after the meeting is closed. It also exposes concurrency behavior ('a simultaneous edit by somebody else is silently overwritten') and the required 'manage outcomes' permission (403 otherwise), which annotations do not provide.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose, then organized into usage, pitfalls, and cross-references. Every sentence adds information: timing constraints, concurrency implications, permission requirements, return response shape, and related tools. Despite its length, it is tightly structured with no filler, making it appropriately sized for the tool's complexity.

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

  Completeness5/5

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

  Given the tool's operational complexity (timing, permissions, concurrency), the description covers all necessary context: what happens on closed meetings, lack of lock_version, 403 condition, and the success response shape ('same shape as add_meeting_outcome'). With an output schema present, the description does not need to detail return fields, so this is complete for an agent to invoke the tool correctly.

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

  Parameters3/5

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

  The input schema already provides 100% parameter descriptions, including omit behavior and constraints (e.g., 'Omit to keep the current one' and 'Switching to work_package needs a linked work package'). The description adds the partial-update rule 'Only the parameters you pass are sent,' but this is largely reinforced by the schema's per-field omission notes. No significant semantic gap exists, so a mid-range score is appropriate.

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

  Purpose5/5

  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: 'Correct a recorded outcome's kind, text or linked work package.' It clearly identifies the tool as an update operation for existing meeting outcomes, distinguishing it from sibling tools like add_meeting_outcome and delete_meeting_outcome by focusing on correction/update.

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

  Usage Guidelines5/5

  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 while the meeting still runs: fix a typo in the minutes, upgrade an information note to a decision, or attach the follow-up ticket...' It also names cross-references such as get_meeting for retrieving the outcome id, add_meeting_outcome for kind rules, and delete_meeting_outcome for removal, providing clear alternative guidance.

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

• create_newsA
  4.8/5.0
  Behavior5/5

  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.

  Conciseness4/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• list_file_linksA
  4.8/5.0
  Behavior5/5

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

  Annotations already signal readOnly, idempotent, and non-destructive, but the description adds considerable detail: the list is fetched in full (has_more always false), 404/403 results return an empty list with a note, and the permission field semantics are explained ('View allowed' vs other values). It also discloses that URLs require the user's own OpenProject login and that the server cannot fetch bytes. 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.

  Conciseness4/5

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

  The description is lengthy but well-structured, moving from a clear definition to return details, pitfalls, and related tools. Every sentence contributes important nuance, especially around edge-case behaviors. It could be trimmed slightly, but the density warrants a 4 rather than 3.

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

  Completeness5/5

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

  Given the tool's complexity and the rich output schema, the description is remarkably complete: it explains the return payload fields, error patterns, permission implications, and relationships to sibling tools. It addresses all foreseeable agent questions without redundancy.

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

  Parameters4/5

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

  The schema already provides 100% coverage of the single parameter, so baseline is 3. The description adds value beyond the schema by clarifying that work_package_id is never an attachment id or project id and that it comes from specific list/search tools. This extra context justifies a 4.

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

  Purpose5/5

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

  The description opens with 'List the external-storage files (Nextcloud, OneDrive/SharePoint) linked to a work package.' This is a specific verb+resource+scope statement that clearly identifies the tool's purpose. It also explicitly distinguishes file links from attachments, setting it apart from the sibling list_attachments.

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

  Usage Guidelines5/5

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

  It says 'Use this to answer "which documents belong to this ticket"' and instructs pairing with list_attachments because the two lists are disjoint. It further states download_attachment does not work on these links and points to get_work_package as the provenance. This gives explicit when-to-use, when-not-to-use, and alternative guidance.

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

• list_permissionsA
  4.8/5.0
  Behavior5/5

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

  The description goes well beyond the readOnly/openWorld/idempotent hints by disclosing how it resolves the current user ID (from cached users/me), the API's lack of a 'me' value, the 500-capability cap with notes, the subset-of-permissions caveat, and that permission is only a necessary condition (validations can still fail). 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.

  Conciseness4/5

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

  The description is longer than typical, but each section (purpose, caveat, pitfalls, cross-references) earns its place for a tool with non-obvious edge cases. It is well-structured with bolded lead-ins; while dense, it remains scannable and free of fluff.

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

  Completeness5/5

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

  Given the tool's complexity, the description covers the operational context thoroughly: when to use it, what it returns (items, principal, capability_count, check), its limitations (subset, cap, no 'me'), and how it relates to sibling tools. The output schema exists, so return-value details are already structured, and the description adds the critical 'miss ≠ denied' interpretation.

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

  Parameters4/5

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

  The schema already covers both parameters with full descriptions, so the baseline is 3. The description adds extra value by reinforcing the purpose of each parameter with practical examples ('may I create work packages HERE') and explaining the 'check' predicate behavior, which goes beyond the schema's syntax-level detail.

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

  Purpose5/5

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

  The description opens with 'List what the authenticated user is allowed to do, globally or in one project' — a specific verb, clear resource, and scope. It immediately distinguishes itself from the many work-package/project tools by focusing on capabilities and even contrasts itself with tools like list_memberships and list_roles.

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

  Usage Guidelines5/5

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

  Explicitly states when to use: before a write that might 403, to explain failures, or to choose between tools. It also gives exclusions ('does not return a user profile', cannot ask about another user) and cross-references sibling tools (list_memberships, list_roles, get_instance_info) for related needs.

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

• list_time_entriesA
  4.8/5.0
  Behavior5/5

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

  The description goes well beyond annotations by disclosing permission-bound visibility, the 2000-entry summing cap, page_size clamping, and the nuance that a small total may reflect permissions rather than actual data. These details complement the readOnlyHint/idempotentHint annotations without any contradiction.

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

  Conciseness4/5

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

  The description is lengthy but well-structured with labeled sections (purpose, examples, response format, pitfalls, cross-references). It front-loads the core function and every sentence adds value, making it appropriately sized for a complex 10-parameter tool.

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

  Completeness5/5

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

  The description covers the response envelope, pagination, sums, group buckets, caps, permissions, and related tools, leaving very little unanswered for an agent. With an output schema present, this level of context is fully sufficient.

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

  Parameters4/5

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

  Although the input schema already documents all 10 parameters, the description adds meaningful cross-parameter behavior, such as how sum_hours aggregates across all matches, fetch_all caps at 500, and work_package_id excludes child work packages. These enrich the schema descriptions and justify a score above baseline.

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

  Purpose5/5

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

  The description opens with 'List logged time, filtered server-side, with an optional accurate total,' a specific verb and resource, and immediately gives concrete example questions. It clearly distinguishes itself from sibling tools like log_time and update_time_entry 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.

  Usage Guidelines5/5

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

  The description includes explicit 'Use it to answer...' usage scenarios and states that filters combine with AND. It lists alternatives for booking, correcting, and deleting entries, and gives exclusions such as permission limits and the exclusion of child work packages.

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

• mark_notificationsA
  4.8/5.0
  Behavior5/5

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

  Goes beyond annotations by describing the return structure (marked, read, ids, message), the 204 No Content behavior, the meaning of 'marked', the idempotent retry safety, the notification id vs resource.id pitfall, and that unknown ids do not fail the call. 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.

  Conciseness4/5

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

  Well-structured with purpose, usage, returns, pitfalls, and cross-references. Every sentence adds value; while longer than a minimal description, the complexity of the API (204, idempotency, id pitfalls) justifies the length. Slightly dense but not wasteful.

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

  Completeness5/5

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

  With 2 well-documented params, annotations, an output schema, and rich behavioral guidance, the description fully equips the agent to select and invoke the tool correctly. Includes all necessary caveats and alternatives.

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

  Parameters4/5

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

  Schema already covers both parameters with descriptions (100% coverage), so baseline 3. The description adds critical semantics: ids come from the 'row id' of list_notifications, not resource.id, and clarifies the 'read' direction is safe with explicit ids.

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

  Purpose5/5

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

  States 'Mark specific notifications read (or unread) in one bulk request' – a specific verb+resource. Distinguishes from siblings by calling itself the 'id-consuming counterpart of list_notifications' and differentiating from mark_all_notifications_read.

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

  Usage Guidelines5/5

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

  Explicitly says 'Use it after you have actually handled what a notification was about' and provides cross-references: 'get the ids from list_notifications' and 'to clear an entire inbox use mark_all_notifications_read'. This is clear when-to-use and alternatives.

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

• search_principalsA
  4.8/5.0
  Behavior5/5

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

  Beyond the readOnlyHint and idempotentHint annotations, the description discloses non-obvious behavior: email/login/status are only returned for visible users ('a null email means not visible to you, not no email'), group principals are assignable, matching is substring-based and broad, and member_of_project filters by membership rather than activity. These are valuable behavioral nuances not captured in annotations.

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

  Conciseness4/5

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

  The description is longer than typical but well-organized into purpose, usage, pitfalls, and cross-references. Every sentence earns its place; there is no filler. The 'Pitfalls' section is particularly high-density. Could be slightly tightened, but structure aids scannability.

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

  Completeness5/5

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

  With no required parameters, an output schema for return envelope, and full schema coverage, the description still adds critical context: id resolution workflow, visibility semantics, and relationship to other tools. It is complete for an AI agent to select and invoke confidently, covering all decision-relevant aspects.

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

  Parameters4/5

  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 guidance over the schema: explains that type='group' includes assignable groups, warns about short queries matching broadly, and clarifies member_of_project usage ('Use it before assigning work — a user who is not a member usually cannot be assigned'). This elevates it above baseline, though not all params get equal attention.

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

  Purpose5/5

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

  The description opens with 'Find users, groups and placeholder users, and get their ids', a specific verb+resource+result statement. It explicitly positions itself as 'the id-producing tool for every principal parameter in this server', distinguishing it from sibling tools like get_user, list_memberships, and create_membership.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use and when-not-to-use guidance: 'Names are never accepted where an id is wanted — resolve here first, and never guess a numeric id'. It also gives example queries ('who is Grace Hopper's account', 'which groups exist') and names alternatives: 'get_user for one user's full detail; list_memberships for who holds which roles; create_membership to grant access; list_roles for role ids'.

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

• set_project_favoriteA
  4.8/5.0
  Behavior5/5

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

  Beyond the annotations (idempotentHint, readOnlyHint=false, destructiveHint=false), the description discloses per-user scoping, idempotent success on repeated calls, version-specific refusal/send behavior, and the deliberate 404 ambiguity. There is no contradiction with the annotations; the description adds substantial context the structured data does not convey.

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

  Conciseness4/5

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

  The description is longer than the calibration examples but well-structured with sections for purpose, use case, return value, pitfalls, and cross-references. Every sentence carries meaningful information; the version pitfalls and 404 ambiguity are necessary for correct use, though some phrasing could be tightened. It is front-loaded with the core action.

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

  Completeness5/5

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

  Given the tool's complexity (version dependency, ambiguous 404, per-user scope), the description is remarkably complete: it covers the return shape, behavioral nuances, fallback instructions, and cross-tool references. The output schema exists, but the description still adds valuable context about version-specific behavior and error interpretation, leaving no significant gap.

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

  Parameters4/5

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

  Both parameters are already fully described in the schema (100% coverage), so the baseline is 3. The description adds a small but useful cross-reference that id_or_identifier comes from list_projects or get_project, and clarifies that favorite is not a toggle, though the schema already says most of this. Overall it adds some value beyond the schema but does not need to compensate for gaps.

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

  Purpose5/5

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

  The opening sentence states a specific verb ('Add or remove') and resource ('a project from the authenticated user's favorites'), making the action and scope unambiguous. It explicitly distinguishes itself from project status and work-package watchers, which are the closest sibling-tool concepts, so it is clearly differentiated.

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

  Usage Guidelines5/5

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

  The description provides an explicit trigger ('when the user asks to pin, star or favorite a project they work in'), names alternatives (list_projects for reading favorites, web UI for older instances), and states exclusions (not project status, not a watcher). This gives the agent clear decision rules for when to invoke the tool.

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

• update_meeting_agenda_itemA
  4.8/5.0
  Behavior5/5

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

  While annotations indicate readOnlyHint=false and destructiveHint=false, the description adds rich behavioral context: only passed parameters are sent, the fresh lock_version is returned, closed meetings reject writes, itemType is create-only, permission requirements (403), and concurrency conflict semantics (409). This goes far beyond what annotations provide and avoids contradiction.

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

  Conciseness4/5

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

  The description is longer than the calibration examples, but every sentence earns its place: overview, examples, return value, pitfalls, and cross-references. It is well structured and front-loaded with the primary purpose, though the density could be slightly reduced without loss.

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

  Completeness5/5

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

  Given the mutation complexity, the description covers partial update semantics, return shape, error cases (422, 403, 409), prerequisites (permissions, open meeting), and cross-references. Even with an output schema present, the behavioral and edge-case coverage is complete and actionable.

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

  Parameters4/5

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

  The input schema already provides 100% coverage with detailed per-parameter descriptions. The tool description adds overarching context like 'Only the parameters you pass are sent' and the meaning of position for reordering, which clarifies interaction between parameters. Schema already carries the load, so the description only needs to add a little extra value.

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

  Purpose5/5

  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: 'Edit one agenda item: retitle it, rewrite its notes, retime, reorder or re-link it.' This clearly distinguishes the tool from siblings like `add_meeting_agenda_item` and `delete_meeting_agenda_item`, using action-oriented language with concrete examples.

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

  Usage Guidelines5/5

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

  It provides explicit usage scenarios ('Use it for...'), plus cross-references to related tools (`get_meeting`, `delete_meeting_agenda_item`, `add_meeting_outcome`). It also states when NOT to use it, e.g., when the meeting is CLOSED. This gives the agent clear decision-making guidance.

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

• add_work_package_commentA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• add_work_package_watcherA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• create_projectA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• create_recurring_meetingA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• create_versionA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• create_work_packageA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• create_work_package_relationA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• delete_attachmentA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• delete_projectA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• delete_recurring_meetingA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• delete_time_entryA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• execute_custom_actionA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• get_github_pull_requestA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• get_instance_infoA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• get_project_phaseA
  4.9/5.0
  Behavior5/5

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

  Beyond the readOnlyHint/idempotentHint annotations, the description discloses important behavioral traits: there is no phases index, ids only come from work package references, phase dates are not exposed, and a 404 covers three distinct error cases. These details meaningfully help an agent anticipate tool behavior and failure modes.

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

  Conciseness5/5

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

  The description is well-structured with an initial summary, a usage trigger, a pitfalls section, and cross-references. Every sentence carries unique information; there is no filler or repetition of schema/annotation content. The length is justified by the tool's edge cases.

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

  Completeness5/5

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

  The description covers the return shape, the prerequisite data source, alternative tools, and the full meaning of a 404 error. Combined with a rich output schema and strong annotations, this description leaves no significant 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.

  Parameters4/5

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

  The input schema already provides 100% coverage and explicitly warns that phase_id is "NOT a definition id from list_project_phase_definitions." The description reinforces this by stating ids only come from work packages' project_phase references. This adds contextual value over the schema alone, though most semantic weight is carried by the schema's own description.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: "Read one project's phase record: name, active flag and its definition." It clearly scopes the tool to a single phase record and lists the exact fields returned, making its purpose unambiguous and distinguishable from broader list/search siblings.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use this tool: "Use it after get_work_package surfaced a project_phase reference..." It also gives a when-not-to-use by pointing to list_projects(in_phase=...) for date-based phase queries and cross-references list_project_phase_definitions for the catalog. This is textbook usage guidance.

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

• get_work_package_schemaA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds rich behavioral context: wire spelling pitfalls, writable:false being an error, allowed_values null for lookup URLs, a 50-item cap, and cache-bypass 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.

  Conciseness5/5

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

  The description is well-structured with a purpose sentence, explicit usage directions, a clear return-format listing, and a dedicated pitfalls section. Every sentence adds value, and it is front-loaded with the main purpose.

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

  Completeness5/5

  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 thoroughly covers when to use, what to expect, pitfalls, and parameter provenance. The output schema exists, so the return-format summary is a bonus, and the description is complete for an agent to invoke this tool correctly.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: project_id must be numeric (not string), type_id is not the name, both ids come from get_project_metadata, and the schema is per project AND type. This enriches the parameter understanding.

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

  Purpose5/5

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

  The description uses a specific verb+resource construction: 'Show which fields a work package of this type accepts in this project.' This clearly distinguishes it from siblings like get_work_package (which reads actual values) and create/update_work_package (which write).

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

  Usage Guidelines5/5

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

  Explicitly states when to call: 'Call it before create_work_package/update_work_package when you need the required fields, when you want a custom field's key or its allowed options, or after a 422 that named a field you do not recognise.' Also names alternatives (search_principals/list_projects) for resolving lookup URLs, providing clear when/when-not context.

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

• list_documentsA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral detail: the call is instance-wide with no project parameter, pagination must be checked via pagination.has_more, and the call can succeed with empty items plus a note when the module is unavailable or permissions are insufficient. It also clarifies that files are not part of the rows. 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.

  Conciseness5/5

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

  The description is structured with a clear lead sentence, a use-case paragraph, a return-format note, and a pitfalls section. Every sentence adds value: no fluff. The length is justified by the complex pitfalls and cross-references, and the front-loaded purpose ensures quick comprehension.

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

  Completeness5/5

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

  The description covers purpose, output format (standard list envelope), navigation, pitfalls (module availability, permissions, pagination), and relationships to other tools. With an output schema present, it appropriately omits full return field details but gives enough context for the agent to invoke it correctly. It is fully self-sufficient for the agent.

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

  Parameters4/5

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

  The schema already provides descriptions for page and page_size with 100% coverage, so the baseline is 3. The description adds practical guidance on how to use pagination ('page through rather than assuming page one is everything') and references pagination.has_more, which enriches the semantic understanding of both parameters beyond the schema.

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

  Purpose5/5

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

  The description opens with 'List the documents visible to you, across every project,' which gives a specific verb, resource, and scope. It distinguishes itself from sibling tools like get_document and list_attachments by explicitly positioning itself as the way to find document IDs, and from search tools by noting it returns all documents rather than filtered results.

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

  Usage Guidelines5/5

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

  The description explicitly states usage: 'Use this to find a document id for get_document or for list_attachments(...)'. It also provides cross-references for related operations (get_document for descriptions, list_attachments for files) and warns when not to rely on a single page, directing the agent to paginate. This gives clear when-to-use and alternative guidance.

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

• list_meetingsA
  4.9/5.0
  Behavior5/5

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

  The description goes well beyond the annotations (readOnlyHint, idempotentHint) by disclosing several behavioral traits: return envelope fields, ISO 8601 UTC format, ordering rules, exclusion of cancelled/recurring templates, the meaning of 'draft' state, and the critical silent-success behavior when meetings module is unavailable (empty items with reason in notes). It also warns that absence may not mean no meetings, which is essential for correct interpretation.

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

  Conciseness5/5

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

  The description is well-structured and front-loaded: first sentence states purpose, followed by usage, return format, pitfalls, and cross-references. Though lengthy, every sentence carries relevant information—no filler. The 'Pitfalls' section is clearly demarcated, improving readability and scanability.

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

  Completeness5/5

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

  Given the tool's complexity (module behavior, silent failures, ordering, exclusions) and the moderate schema/annotations, the description covers all essential aspects: output format, time zone, ordering, edge cases, and error-like conditions. The output schema covers return structure, so the description compensates for any remaining ambiguity about behavioral nuances.

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

  Parameters4/5

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

  Schema coverage is 100% with each parameter described, so the baseline is 3. The description adds extra semantics: it clarifies that project_id takes only the numeric ID (rejecting URL identifiers) and explains the ordering behavior tied to upcoming_only. While these are refinements, they add useful meaning beyond the schema's own descriptions.

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

  Purpose5/5

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

  The description clearly states the tool lists meetings, the schedule side of a project, and explicitly distinguishes it from related tools like get_meeting and create_meeting. It also gives concrete use cases ('when do we next meet', 'what meetings does this project have'), 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.

  Usage Guidelines5/5

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

  The description provides explicit when-to-use guidance: it says to use it to find meeting IDs needed by get_meeting and add_meeting_agenda_item, and to answer schedule questions. It also names alternatives (get_meeting for participants/agenda, create_meeting to schedule, list_projects for project IDs), fulfilling the when-not and alternative criteria.

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

• list_membershipsA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context: the membership id is not the principal/project id, group memberships can cause false negatives, and memberships indicate permission potential, not actual actions. It also describes pagination 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.

  Conciseness5/5

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

  Though longer than typical, it is tightly structured: purpose sentence, use cases, list envelope, Pitfalls paragraph, and Cross-references. Every sentence adds value, and the most important information is front-loaded. The length is justified by the tool's RBAC complexity.

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

  Completeness5/5

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

  For a tool with 4 optional filters and complex access semantics, the description covers use cases, large-result warnings, output envelope, pitfalls, and cross-references. Existing output schema reduces the need to document return values, but the description still provides helpful context. Nothing significant is missing.

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

  Parameters4/5

  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 augments this by explaining practical semantics: project_id supports URL identifiers with an extra lookup cost, combining project_id and principal_id to check one person's roles, and principal_id accepts user/group/placeholder ids. It also notes the no-argument behavior and 'which projects can this person see' use case.

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

  Purpose5/5

  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: 'List who has access to which project, and with which roles.' This clearly distinguishes it from sibling tools like list_roles and list_projects by focusing on membership objects. The title reinforces this without ambiguity.

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

  Usage Guidelines5/5

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

  Explicit use cases are stated: 'Use it before granting or revoking access...', 'to audit a project's member list', and 'to see which projects a principal can reach.' It also names cross-reference tools (list_roles, create_membership, search_principals, list_permissions) and warns about the no-arguments behavior, providing clear alternatives and exclusions.

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

• list_newsA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare it read-only, idempotent, and non-destructive. The description adds substantial context: newest-first sorting, the exact envelope fields (items/pagination/notes), the distinction between summary and full body (fetched via get_news), the meaning of can_manage for permission checking, and edge cases like missing module/permission yielding an empty page with notes rather than an error. It also explains how project_id resolution works and that unknown identifiers fail as not_found. This significantly extends the structured annotations.

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

  Conciseness5/5

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

  The description is well-structured with labeled sections (Use it, Returns, Pitfalls, Cross-references). Every sentence adds meaningful context—purpose, ordering, return format, safety hints via can_manage, and important edge cases—without fluff. It is long but necessary given the tool's nuances.

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

  Completeness5/5

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

  The tool has 3 optional parameters and an output schema, yet the description still explains return values in detail (items fields, pagination, notes) and covers pitfalls like empty pages due to missing permissions and unknown identifiers. It also clarifies the relationship with get_news for full bodies, making it complete for an agent to use correctly.

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

  Parameters4/5

  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 beyond the schema by explaining that project_id comes from list_projects, that omitting it lists across the instance, and that identifier resolution may involve an extra lookup with a not_found failure. It doesn't add extra semantics for page/page_size, but schema already documents them clearly.

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

  Purpose5/5

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

  The description opens with a specific verb+resource+scope: "List project news — the announcements a team publishes on its project overview." It distinguishes itself from siblings by explicitly noting that work-package discussion lives in list_work_package_comments, and cross-references get_news/create_news for other news operations.

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

  Usage Guidelines5/5

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

  Explicit usage examples are given: "Use it to answer 'what was announced recently', to find the id of an entry before reading, editing or deleting it, or to check whether a report was already published." The Pitfalls section also clarifies when not to use it (e.g., don't report 'no announcements' without reading the notes) and points to alternative tools for work-package comments.

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

• list_notificationsA
  4.9/5.0
  Behavior5/5

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

  Beyond the readOnlyHint/idempotentHint annotations, the description reveals important behavioral traits: the inbox is always the token owner's, notifications aggregate multiple changes, reading here does not mark as read, unread_only=false may return a long history, and access loss causes notifications to disappear. It also notes the Enterprise-only dateAlert limitation. This significantly exceeds the annotation baseline.

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

  Conciseness5/5

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

  The description is structured with clear sections: purpose, example questions, envelope format, pitfalls, and cross-references. Every sentence adds practical information for a complex tool. It is front-loaded with the core purpose and stays efficient despite its length.

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

  Completeness5/5

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

  Despite the output schema existing, the description provides a complete picture: return envelope structure, resource semantics, aggregation behavior, read-state implications, access edge cases, and explicit sibling tool handoffs. No major gaps remain for an agent to correctly invoke and interpret this tool.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds value by warning about 'unread_only=false can return a very long history' and advising page size tuning. It also clarifies that 'mentioned' is what answers 'who needs me?', but this is also in the schema. The extra context on unread_only and pagination justifies a 4.

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

  Purpose5/5

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

  The description clearly states the tool reads the authenticated user's OpenProject inbox, using the specific verb 'Read' and resource 'inbox'. It explicitly distinguishes itself from siblings by noting 'it is the only tool that sees notifications', making its purpose unambiguous.

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

  Usage Guidelines5/5

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

  The description gives explicit 'Use this to answer' framing for common questions ('what needs my attention?') and provides alternatives via cross-references (mark_notifications, mark_all_notifications_read, get_work_package). This clearly tells the agent when to use this tool and what other tools handle related actions.

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

• list_projectsA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: the standard list envelope, explicit pagination ('Nothing is truncated silently — page explicitly until has_more is false'), and pitfalls (search scope, direct-children semantics, status_code codes, workspace_type mixing, in_phase date semantics).

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

  Conciseness5/5

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

  The description is long but every section earns its place: overview, use cases, return envelope, pitfalls, and explicit alternatives. It is front-loaded with the core purpose and structured logically, avoiding fluff. For a tool with 10 parameters and significant edge cases, this length is justified.

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

  Completeness5/5

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

  Given the tool's complexity (10 parameters, many edge cases, and many sibling tools), the description is remarkably complete. It covers the result envelope, pagination behavior, parameter interplay, version-specific behavior (OpenProject 17.x), and redirects to relevant alternatives. An output schema exists, so return-value detail is appropriately left to the schema.

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

  Parameters4/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining behavioral implications of specific parameters: 'parent_id returns direct children, so a deep hierarchy needs one call per level', 'in_phase tests phase dates', and that search ignores descriptions. These go beyond the raw schema text, earning a 4.

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

  Purpose5/5

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

  The description states a specific verb+resource ('List projects') and clearly differentiates from siblings by positioning this tool as the id-producing path for every project_id, and by naming alternatives (get_project, get_project_metadata, list_work_packages). It also enumerates concrete use cases (name→id, enumerate sub-projects, review off track).

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

  Usage Guidelines5/5

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

  Explicit when-to-use guidance is provided ('Use this to turn a project name into the id...'), and exclusions are named with alternative tools ('For a single project's description... use get_project; For the types... use get_project_metadata; To list a project's work packages use list_work_packages'). This gives clear steering versus alternatives.

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

• list_remindersA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations (readOnly, idempotent, openWorld), the description discloses important behavioral traits: reminders are personal and cannot show others' data, only upcoming reminders are returned (fired/completed ones are dropped), and an empty result does not mean nothing was scheduled. It also clarifies the distinction between reminder IDs and work package IDs.

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

  Conciseness5/5

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

  The description is well-structured: a clear one-sentence summary, a brief usage section, a pitfalls subsection, and cross-references. Every sentence adds meaningful information without fluff, and the front-loaded purpose makes it easy to parse.

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

  Completeness5/5

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

  Given the tool's simplicity (no parameters) and the presence of an output schema, the description covers all necessary context: personal scope, upcoming filter, return envelope structure, and pitfalls. It fully prepares the agent to use the tool correctly without needing to consult external documentation.

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

  Parameters4/5

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

  The tool has zero parameters, so the baseline is 4. The description properly clarifies that there are no parameters and that the output is the full list of personal upcoming reminders, which complements the empty input schema.

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

  Purpose5/5

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

  The description begins with a specific verb and resource: "List your own upcoming work-package reminders." It clearly distinguishes this tool from siblings by scoping to personal and upcoming reminders, and cross-references related tools to avoid ambiguity.

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

  Usage Guidelines5/5

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

  Explicit use cases are provided: answering what you asked to be reminded about, checking before creating another reminder, and finding deferred work packages. Cross-references clearly state when to use set_work_package_reminder, list_notifications, and get_work_package instead.

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

• list_rolesA
  4.9/5.0
  Behavior5/5

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

  Annotations already mark it read-only, idempotent, and non-destructive, but the description adds substantial context: the list envelope with has_more:false, the item shape, the effect of include_permissions, configurable role names, assignability restrictions, and version-dependent permission arrays. This goes far beyond annotation defaults and warns of realistic pitfalls.

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

  Conciseness5/5

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

  Well-structured with a lead sentence, a clear note on id usage, a return-format paragraph, a Pitfalls section, and a Cross-references section. Every sentence adds value, no fluff, and important details are front-loaded. Length is justified by the richness of guidance.

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

  Completeness5/5

  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 explains the envelope and item shape. It covers the tool's role in the wider workflow, its pitfalls, and cross-references to related tools. For a single-parameter list tool, this is as complete as one could reasonably need.

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

  Parameters4/5

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

  Schema coverage is 100% and already describes include_permissions well, so baseline is 3. The description adds extra practical context by explaining the performance cost (thousands of tokens) and advising when to enable it, which genuinely enhances the schema's meaning. Minor gap: no mention of default false beyond schema, but that's already there.

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

  Purpose5/5

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

  The description clearly states it lists instance-defined roles with their IDs, using a specific verb and resource. It distinguishes itself from sibling tools by explaining its role as the id-producing tool for membership operations, making its purpose unmistakable.

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

  Usage Guidelines5/5

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

  Explicitly frames this as the required source for role_ids in membership tools, says role names are never accepted, and names alternatives: list_memberships for usage, list_permissions for current user permissions, especially after a 403. Provides 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.

• mark_all_notifications_readA
  4.9/5.0
  Behavior5/5

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

  The description adds significant behavioral context beyond the annotations: there is no undo, the return value `marked` is counted immediately before the bulk update (with a possible race nuance), and the tool deliberately only marks read, with no reverse twin. This goes well beyond the annotations' `readOnlyHint`, `idempotentHint`, and `destructiveHint` by explaining the operational consequences.

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

  Conciseness5/5

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

  The description is long but taut—every sentence earns its place: purpose, use cases, caveat, return semantics, and cross-references. It is front-loaded with the core purpose and structured logically, making it dense with operational guidance without any fluff.

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

  Completeness5/5

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

  Given the tool's complexity, the rich annotations, and the presence of an output schema, the description covers all bases: when to use it, what it does, what to check beforehand, what it returns, and how to reverse the action. No important context for invocation is missing.

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

  Parameters4/5

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

  The input schema already provides 100% coverage for `reason` and `project_id` with clear descriptions. The tool description enriches this by explaining that both parameters 'narrow that blast radius' and 'do not create a preview', plus clarifying the default all-notifications behavior when omitted. This adds meaningful nuance beyond the schema, though it doesn't need to redefine the parameter formats.

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

  Purpose5/5

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

  The description opens with a concrete verb and resource: 'Mark everything matching the filters as read', with the default scope clearly defined as 'the whole inbox'. It distinguishes this bulk operation from the per-id sibling `mark_notifications` and the read-only `list_notifications`, making the tool's purpose unmistakable.

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

  Usage Guidelines5/5

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

  It explicitly states when to use it ('clear my notifications', 'I have dealt with everything in project X') and recommends previewing with `list_notifications(unread_only=true, ...)` using the same filters first. It also directs the reverse operation to `mark_notifications(ids=[...], read=false)` and warns about the lack of undo, giving clear when-to and when-not-to guidance.

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

• run_queryA
  4.9/5.0
  Behavior5/5

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

  The description adds substantial behavioral detail beyond the annotations: it states queries run on read and return rows 'as they are right now', explains the standard list envelope plus the `query` addition, and details pitfalls such as `groups`/`sums` being server-side computed, `page_size` omission behavior, `override_filters` replacing stored filters, and the 422 error meaning. This contextualizes the readOnly/idempotent annotations without contradicting them.

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

  Conciseness5/5

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

  The description is efficiently structured: it leads with a purpose statement, then describes the result envelope, follows with a 'Pitfalls' paragraph highlighting key behavioral caveats, and ends with cross-references. Every sentence earns its place, and despite its length, there is no wasted text.

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

  Completeness5/5

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

  For a 4-parameter tool with an output schema, this description is exceptionally complete. It covers the full result shape, server-side computation quirks, pagination behavior, error semantics, and the meaning of the `query` field in the response. It also provides cross-tool references, making it sufficient for an agent to use safely and effectively.

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

  Parameters4/5

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

  The input schema itself has 100% coverage with detailed descriptions, so the baseline is 3. The description adds meaningful nuance beyond the schema: it clarifies that `override_filters` replaces stored filters rather than narrowing them, and that omitting `page_size` keeps the query's own stored page size. This supplemental guidance enhances but doesn't fully replace schema documentation.

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

  Purpose5/5

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

  The description opens with 'Run a saved view and get its work packages', which is a specific verb+resource pairing that clearly identifies the tool's function. It also distinguishes itself from siblings by cross-referencing 'list_work_packages' for ad-hoc filtering and 'get_work_package' for opening a single row, 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.

  Usage Guidelines5/5

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

  The description explicitly provides usage guidance: it states the tool is the 'fastest way to answer with a team's own definition of the sprint or our bugs', and it names alternatives in the cross-references section ('find query ids with list_queries; equivalent ad-hoc filtering lives in list_work_packages; open a single row with get_work_package'). This gives clear when-to-use vs 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.

• save_queryA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint=false, openWorldHint=true, etc.), the description discloses the internal POST /queries/form validation call, the failure mode returning violations with nothing saved, the two-step star behavior, filter-count mismatch handling, and custom-field limitations. This gives the agent a realistic model of side effects and failure.

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

  Conciseness5/5

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

  The description is long but structured: purpose, usage, behavior, pitfalls, cross-references. Each section adds essential operational knowledge, and the use of a 'Pitfalls' paragraph front-loads critical warnings. No wasted sentences.

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

  Completeness5/5

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

  The description covers purpose, usage, behavior, return format, error handling, side effects, and relationships to sibling tools. Combined with the exhaustive schema and output schema, the agent has everything needed to invoke this tool correctly.

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

  Parameters4/5

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

  The input schema already covers 100% of parameters with detailed descriptions, so baseline is 3. The description adds value by highlighting semantic pitfalls (values are ids not names, customField12 handling, empty filters meaning 'show every status') that are not fully covered in the schema. However, much of the parameter detail overlaps with the schema descriptions.

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

  Purpose5/5

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

  The description opens with a clear verb-object: 'Save a filter set as a reusable OpenProject view the whole team can open.' It distinguishes from siblings by explicitly contrasting with run_query, list_queries, and list_work_packages, and notes editing/deleting is intentionally not offered.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use ('when a filter combination is worth keeping'), recommends validating with list_work_packages first, and names alternatives (list_queries, run_query, list_work_packages, list_projects) with specific roles. It also tells when not to use it (editing/deleting should be done in the UI).

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

• set_work_package_reminderA
  4.9/5.0
  Behavior5/5

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

  The description discloses far more than annotations alone: it explains the upsert semantics (creates or updates), that passing null deletes the reminder, why no confirm is needed (only the personal notification is removed), the one-active-reminder-per-person limit, timezone requirements, past-rejection behavior, and that fired reminders disappear from the API. This is rich context beyond the readOnlyHint/idempotentHint annotations.

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

  Conciseness5/5

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

  The description is longer than average, but every sentence earns its place. It is front-loaded with the core purpose, followed by usage, a clear explanation of the null behavior, and a structured 'Pitfalls' section. Each paragraph has a distinct role, making it easy to scan and digest without wasted words.

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

  Completeness5/5

  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 exceptionally complete. It covers behavior, edge cases, personal nature, alternatives, and even mentions the return value ('Returns action (created/updated/deleted/unchanged) and the resulting reminder'). The output schema exists, so return details are not required, but the description still provides enough context for correct invocation.

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

  Parameters4/5

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

  The input schema already provides 100% coverage with detailed descriptions for all three parameters. The description does add extra nuance not in the schema: clarifying timezone refusal ('a bare '2026-08-03T09:00' is refused rather than guessed at'), past reminders being rejected, and the inability to stack reminders. This goes beyond a simple restatement, though the schema does most of the heavy lifting.

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

  Purpose5/5

  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: 'Set, change or clear your personal reminder on a work package.' It immediately distinguishes the tool from siblings by clarifying it handles personal reminders, and the cross-references at the end (list_reminders, add_work_package_watcher, add_work_package_comment) reinforce the differentiation.

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

  Usage Guidelines5/5

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

  Explicit guidance is given: 'Use this when something should resurface later' with concrete examples. The description also provides clear exclusions and alternatives: reminders are personal, so for a colleague use add_work_package_watcher or add_work_package_comment with an @-mention, and list_reminders shows all pending reminders.

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

• update_newsA
  4.9/5.0
  Behavior5/5

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

  Discloses important behaviors beyond annotations: partial-update semantics, summary/description replace rather than append, no lockVersion leading to silent overwrites, and required 'manage news' permission with 403 interpretation. This adds rich context not covered by readOnlyHint/idempotentHint flags.

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

  Conciseness5/5

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

  Well-structured and front-loaded: the main purpose appears first, followed by use cases, pitfalls, and cross-references. Every sentence adds value, and the length is appropriate given the complexity of the tool's behavior.

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

  Completeness5/5

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

  Despite having an output schema (so return format need not be detailed), the description covers concurrency, replacement semantics, fixed fields, permission requirements, and related tools. It is complete for a complex update operation.

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

  Parameters4/5

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

  Schema covers 100% of parameters with detailed meanings, so the baseline is 3. The description adds extra context about partial-parameter transmission and the absence of a lock parameter, enhancing understanding beyond the schema, but the schema already carries most of the burden.

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

  Purpose5/5

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

  Begins with 'Correct or rewrite a published news entry,' giving a specific verb and resource. The description lists concrete use cases (fix headline, refresh report, clear teaser) and cross-references get_news, delete_news, and create_news, clearly distinguishing it from sibling tools.

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

  Usage Guidelines5/5

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

  Explicitly states when to use ('Use it to fix a headline...') and when not to: project/author cannot be changed (publish a new entry), delete_news for removal, create_news for follow-ups. This gives clear context and explicit alternatives.

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

• update_projectA
  4.9/5.0
  Behavior5/5

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

  Description discloses validation via 'POST /projects/{id}/form' and violations, partial-update semantics ('Only the parameters you pass are sent — omitted fields are never rewritten'), absence of lockVersion, and pitfalls around REPLACE semantics and archiving. Annotations are minimal, so this context is vital and highly transparent.

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

  Conciseness5/5

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

  The description is long but well-structured with sections for use cases, validation, partial updates, return type, pitfalls, and cross-references. Every sentence adds unique value, so it earns its length; the core purpose is front-loaded in the first line.

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

  Completeness5/5

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

  Covers validation, partial-update behavior, return shape (via get_project reference), side effects of archiving, and intended alternatives. With an output schema present, no further return documentation is needed, and the description fully prepares an agent for correct invocation.

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

  Parameters4/5

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

  Schema already documents all 8 parameters at 100% coverage, so baseline is 3. Description adds crucial operational meaning: 'Only the parameters you pass are sent' clarifies null/default semantics, and pitfalls like 'active=false archives' and 'description REPLACES' enrich the parameter behavior beyond schema descriptions.

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

  Purpose5/5

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

  The description opens with 'Change a project's name, description, visibility, parent, status or archived state', a specific verb+resource+fields. It clearly distinguishes from siblings like update_work_package, create_project, and delete_project by naming project-specific attributes and the archived state.

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

  Usage Guidelines5/5

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

  Explicitly states when to use: 'Use it to record a status change... to rename or re-parent a project, to publish it, or to archive it'. It also provides exclusions: 'Changing ``identifier`` is deliberately not offered' and cross-references get_project/delete_project/list_projects for related tasks.

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

• update_versionA
  4.9/5.0
  Behavior5/5

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

  Discloses behavior well beyond annotations: validation via POST /versions/{id}/form returning violations, partial-update semantics with concurrent edit survival, absence of lockVersion, 409 meaning resource-level change, end_date→endDate mapping, description replacement, and the effect of closing. This is rich, trustworthy context.

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

  Conciseness4/5

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

  The description is long but well-structured into lead, use cases, validation/concurrency, pitfalls, and cross-references. Almost every sentence earns its place, though a few points (e.g., end_date/endDate mapping) slightly duplicate the schema's own param descriptions.

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

  Completeness5/5

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

  Given 7 parameters, an output schema, and annotations, the description is fully complete: it explains behavior, side effects, validation failure mode, concurrency, pitfalls, and related tools. The return shape is adequately handled by referencing create_version's shape without over-explaining.

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

  Parameters5/5

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

  Even though schema coverage is 100%, the description adds crucial semantics: only passed parameters are sent, end_date maps to API endDate, description REPLACES text, null clears values, and omitted parameters stay untouched. This complements the schema rather than repeating it.

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

  Purpose5/5

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

  Opens with a specific verb and resource: “Change a version's name, dates, description, status or sharing.” It clearly distinguishes itself from related tools by naming concrete use cases and cross-referencing list_versions, delete_version, and update_work_package for different intents.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use guidance: move sprint dates, close a release, widen sharing. It also states when NOT to use it (defining project cannot change—create a new version; delete_version when the version must disappear; update_work_package to move work packages), which is exemplary.

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

• update_work_package_relationA
  4.9/5.0
  Behavior5/5

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

  The description adds substantial behavioral context beyond annotations, including the plain-overwrite/no-conflict-detection behavior, the silent replacement of concurrent edits, and the rescheduling side effect of raising lag. Annotations only hint at idempotency and non-read-only, so this fills the gap.

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

  Conciseness5/5

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

  The description is well-structured with a clear opening line, a 'Use it to' section, pitfalls, and cross-references. It is front-loaded with the purpose and each sentence adds value. Despite length, it remains focused and readable.

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

  Completeness5/5

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

  For a tool with 4 parameters and an output schema, the description covers all critical aspects: what can be updated, what cannot be changed, concurrency behavior, side effects, and alternatives. The existing output schema covers return values, so no further explanation is needed.

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

  Parameters4/5

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

  Schema coverage is 100%, so parameter semantics are already strong. The description adds the runtime constraint that at least one of type, lag, or description must be given, and notes the scheduling implication of 'follows'/'precedes'. This goes beyond what the schema states.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Change an existing relation's type, lag or description.' It uses a specific verb and resource, and distinguishes itself from siblings by noting that the two work packages cannot be changed here and by cross-referencing create/delete relation tools.

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

  Usage Guidelines5/5

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

  The description provides explicit use cases ('widen the gap... correct a link... explain why two work packages are connected'), a clear exclusion ('The two work packages cannot be changed here'), and cross-references to alternative tools (create/delete/get). It also warns about the at-least-one-field requirement.

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

• upload_attachmentA
  4.9/5.0
  Behavior5/5

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

  The description discloses substantial behavioral detail beyond annotations: local existence/size pre-checks causing instant failure, the edit-permission requirement on the container, extension-restriction behavior with validation_failed and allowlist hint, and the filename source (file_name vs multipart). This fully surfaces operational traits without contradicting the annotation hints (readOnlyHint=false, destructiveHint=false).

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

  Conciseness5/5

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

  The description is long but every sentence adds value: usage, pre-check behavior, return fields, pitfalls, alternative tool, and related tools. It is structured into clear scannable segments and avoids redundancy with the schema. For a tool with this complexity, the length is warranted.

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

  Completeness5/5

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

  The description covers permissions, error conditions (extension restrictions, oversized files), naming semantics, the return row and its downstream use (id feeds download_attachment), and guidance for the brand-new container case. With an output schema present and five parameters, nothing essential is left unexplained.

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

  Parameters4/5

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

  Schema coverage is 100% and each parameter already has a thorough description, so the baseline is 3. The description adds extra semantics for file_name ('This is the only thing that decides the stored name... ignores the multipart filename') and clarifies container_id usage for comment (activity id). These additions go beyond the schema, justifying a 4.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: 'Attach a local file to a work package, wiki page, meeting, document, budget or comment.' This clearly distinguishes it from sibling tools like download_attachment, list_attachments, and delete_attachment while naming the exact containers it targets.

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

  Usage Guidelines5/5

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

  Explicit when-to-use guidance is given: 'Use it when a file that already exists on the server's machine should be added to an existing container.' It also names an alternative with a concrete parameter hint: 'to give a brand-new work package its files use create_work_package(attachment_paths=[...]) instead.' Related tools are listed for reverse operations.

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

• add_meeting_outcomeA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• cancel_recurring_meeting_occurrenceA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• copy_projectA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• create_meetingA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• delete_meetingA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• delete_meeting_agenda_itemA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• delete_meeting_outcomeA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• download_attachmentA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• get_project_metadataA
  5/5.0
  Behavior5/5

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

  Annotations already declare read-only, idempotent, and non-destructive hints, but the description goes further. It discloses cache behavior (300s TTL, refresh=true), the empty-list-with-notes behavior when time tracking is disabled, per-row flag semantics, and the localization caveat for status names—all beyond what annotations convey.

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

  Conciseness5/5

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

  The description is somewhat long but every sentence earns its place—each covers a distinct aspect: purpose, timing, row structure, pitfalls, and alternatives. It is front-loaded with the most important use case, well-paragraphed, and free of filler.

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

  Completeness5/5

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

  Given the tool's complexity and the existence of an output schema, the description is exceptionally complete. It covers invocation timing, parameter behavior, return value shape, caching, edge cases, and sibling tool pointers, fully equipping an agent to select and invoke correctly.

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

  Parameters5/5

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

  Schema coverage is 100%, but the description adds meaningful semantics: project_id narrows types and fills versions/categories/activities, while refresh bypasses the cache after admin changes. This enriches understanding far beyond the schema's generic parameter descriptions.

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

  Purpose5/5

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

  The description clearly states the tool lists valid ids and names for the instance, with the specific verb 'List' and a clear resource scope. It also differentiates itself from siblings by explicitly naming get_work_package_schema and list_projects as alternatives.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use guidance: 'Call it before any create or update, before filtering by ids, and whenever a write fails with an allowed-values error.' It also names alternatives for other lookup needs, leaving no ambiguity about when to choose this tool.

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

• get_work_package_git_activityA
  5/5.0
  Behavior5/5

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

  Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false already present, the description adds crucial behavioral context: the distinction between internal `id` and human-facing `number`, the fact that 'closed' does not imply 'merged', and the error-handling behavior where 403/404s are reported in `notes` instead of being raised. It also discloses that links are only created via text mentions in commit messages or MR/PR descriptions, not by the API.

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

  Conciseness5/5

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

  The description is long but deliberately structured: purpose, use cases, return shape, availability semantics, pitfalls, and cross-references. Every sentence carries weight—none are filler. The critical warnings (id vs number, closed vs merged, notes for errors) are essential for correct invocation and interpretation. It front-loads the purpose and then layers details logically.

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

  Completeness5/5

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

  Given the tool's complexity (multiple source types, availability flags, CI status, pitfalls), the description covers every operational aspect: what data comes back, what each field means, how errors surface, and how links are created. It also points to companion tools for deeper detail, and the output schema covers the exact return shape. There is no obvious gap that would leave an agent guessing.

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

  Parameters5/5

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

  The schema already describes both parameters with 100% coverage. The description goes further by explaining the concurrency behavior of `include` ('they are fetched concurrently, so narrowing this saves little') and the fact that availability is always reported for all three sources regardless. It also strongly advises against guessing `work_package_id` and tells the agent where it comes from, adding trust and safety guidance.

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

  Purpose5/5

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

  The description opens with a specific and vivid statement: 'Show the code behind a work package: commits, pull/merge requests and CI status.' It clearly names the resource (work package) and the action (show git activity), and enumerates the three concrete result categories. This unambiguously distinguishes it from siblings like get_work_package or list_work_package_comments.

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

  Usage Guidelines5/5

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

  Explicitly prescribes when to use the tool: 'Use this for "is this ticket implemented", "what shipped for it", "did CI pass", "which branch/PR is this in".' It also names alternatives and cross-references: full PR detail via get_github_pull_request, the ticket via get_work_package, and the discussion via list_work_package_comments. 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.

• list_attachmentsA
  5/5.0
  Behavior5/5

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

  The description discloses significant behavioral traits beyond the annotations: the upstream collection is not paginated and has_more is always false; the status field represents virus-scan state with downloadable vs. quarantined values; and a 404 can indicate an invalid container or a disabled module. This adds context that the readOnly and idempotent hints do not cover.

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

  Conciseness5/5

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

  The description is structured logically with a clear first sentence, then a definition of containers, usage guidance, return format, pitfalls, and related tools. Every sentence earns its place; there is no unnecessary verbosity. It is long but information-dense and well-organized.

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

  Completeness5/5

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

  Given the tool's moderate complexity (multiple container types, virus scan status, pagination behavior), the description covers all necessary aspects: what it does, when to use it, return row fields, pitfalls, and related tools. The presence of an output schema is acknowledged but the description still explains the envelope and status semantics, making it complete for an agent.

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

  Parameters5/5

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

  While the schema already provides descriptions for both parameters, the description adds crucial semantics: 'container_id identifies the container, not the file,' and explains that container_type='comment' requires passing an activity id from list_work_package_comments. This extra detail goes beyond the schema, clarifying ambiguous cases.

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

  Purpose5/5

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

  The description begins with 'List the files attached to one container,' which is a specific verb+resource statement. It defines containers as work packages, wiki pages, meetings, documents, budgets, and comments, and explicitly differentiates itself from related tools like download_attachment, upload_attachment, and get_work_package(include=['attachments']).

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

  Usage Guidelines5/5

  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 this to discover attachment ids before calling download_attachment, or to check what a work package already carries.' It also names alternatives in the 'Related' section, clarifying when not to use this tool. Pitfalls, such as the 404 meaning, further guide usage context.

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

• list_versionsA
  5/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint and idempotentHint, but the description adds rich behavioral context: shared versions' `project` refers to the defining project, closed versions refuse work packages, instance-wide listings are capped at 100 with pagination, and `include_sprints` depends on the backlogs module. 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.

  Conciseness5/5

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

  The description is long but every sentence earns its place: it front-loads the purpose, then covers usage, return format, pitfalls, and cross-references in a clear, logical structure. There is no filler or repetition.

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

  Completeness5/5

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

  The description covers return envelope fields (`items`, `pagination`, `notes`), edge cases (shared versions, closed versions, missing backlogs module), and related tools. With an output schema present, this is more than sufficient 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.

  Parameters5/5

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

  While the input schema already describes both parameters, the description adds operational meaning beyond the schema: `project_id` includes versions shared from parent projects, and `include_sprints` merges backlogs rows with `source='sprint'` and explains the behavior when backlogs is absent. This is a substantial value-add.

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

  Purpose5/5

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

  The opening sentence 'List versions (releases, milestones, sprints) you can assign work packages to' precisely names the verb and resource, and the cross-reference section distinguishes it from create_version, update_version, delete_version, and list_work_packages. The purpose is unambiguous and well-differentiated from siblings.

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

  Usage Guidelines5/5

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

  The description explicitly says when to use it ('Use it to turn 'Sprint 12' or 'release 2.1' into the version id...') and provides when-not-to-use guidance in the pitfalls ('narrow with project_id rather than assuming you saw everything'). The cross-references name exact alternatives for each adjacent task, such as get_project_metadata and list_work_packages.

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

• list_work_package_commentsA
  5/5.0
  Behavior5/5

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

  Annotations already declare readOnly/idempotent/non-destructive, and the description adds significant behavior beyond that: the upstream endpoint is unpaginated, the tool fetches the full journal and pages locally, entries are oldest-first, and comments may be truncated with a recovery path via activity_id. 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.

  Conciseness5/5

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

  Though long, the description is tightly structured with labeled 'Pitfalls' and 'Cross-references' sections. Every sentence adds operational value, and the main purpose is front-loaded. There is no redundancy or filler.

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

  Completeness5/5

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

  The description is complete for the tool's complexity: it explains the return envelope (items, pagination, notes), unusual upstream behavior, truncation, and links to related tools. With an output schema present, no further explanation of return values is needed.

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

  Parameters5/5

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

  Input schema covers 100% of parameters with descriptions, giving a baseline of 3. The description enriches this by explaining the practical implications: page/page_size meaning in the context of oldest-first ordering, cost trade-offs, truncation behavior tied to max_comment_chars, and the activity_id round-trip for reading full entries. This goes well beyond the schema.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: 'Read the comment thread and change history of a work package.' It clearly distinguishes this from siblings like add_work_package_comment or get_work_package by stating exactly what is returned (comment entries, parsed field-change entries). The scope is unambiguous.

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

  Usage Guidelines5/5

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

  Explicit usage guidance is provided: 'Use this whenever the question is "what did people say about this ticket" or "what changed on it"'. It also names alternatives for related actions (add_work_package_comment, get_work_package, list_attachments), helping the agent choose between tools.

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

• list_work_packagesA
  5/5.0
  Behavior5/5

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

  Even though annotations already declare readOnly/openWorld/idempotent, the description adds critical behavioral context: it returns only open work packages unless status_scope/status_ids are passed, status_ids overrides status_scope, and groups/sums are computed server-side over the whole filtered set independent of paging. It also warns that IDs differ per instance and must come from get_project_metadata.

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

  Conciseness5/5

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

  The description is tightly structured with a clear opening label, use-case paragraph, return-envelope paragraph, pitfalls paragraph, and sibling-pointer paragraph. Every sentence delivers actionable information, and despite covering a complex 30-parameter tool, it remains readable and front-loaded.

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

  Completeness5/5

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

  Given the tool's complexity (30 parameters, 0 required, rich schema, output schema, and many siblings), the description covers the essential use cases, limitations, return shape, and distinctions from adjacent tools. It is self-sufficient for an agent to know when and how to invoke it correctly.

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

  Parameters5/5

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

  Schema coverage is 100%, but the description adds semantic value by translating natural-language queries into parameter combinations (overdue → due_before, unassigned → assignee=['none'], nearly done → percentage_done_min=80, subtasks → parent_id). It also clarifies cross-parameter interactions (status_ids overrides status_scope) and caveats like 'never re-add them from the rows on one page.'

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

  Purpose5/5

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

  The description opens with 'List work packages with structured filters — the workhorse read tool', clearly identifying the verb, resource, and scope. It explicitly distinguishes itself from siblings by pointing to search_work_packages for text lookups and get_work_package for single-package details.

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

  Usage Guidelines5/5

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

  It provides concrete when-to-use guidance with example queries ('what is assigned to me', 'what is overdue', 'what is in this sprint') and maps them to specific parameters. It explicitly names alternatives: 'For text lookups use search_work_packages; for one work package's description, custom fields and children use get_work_package.'

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

• toggle_comment_reactionA
  5/5.0
  Behavior5/5

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

  Annotations already mark readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description goes far beyond that by explaining the toggle semantics (double-invocation leaves state unchanged), authentication ownership rules, the 400 rejection for journal entries, version requirements, and the 404/version-hint behavior. This is rich behavioral detail that helps the agent anticipate failures.

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

  Conciseness5/5

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

  The description is detailed but tightly organized: purpose, usage guidance, pitfalls, and cross-references. Every sentence carries operational value. While long, it is appropriately structured with clear sections and bolded pitfalls, and it front-loads the core purpose before diving into edge cases.

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

  Completeness5/5

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

  Given the tool's toggle behavior, auth constraints, version dependency, and error modes, the description covers all these aspects comprehensively. It explains return state, references the output schema implicitly, and cross-links to the exact sources for the required activity_id. Nothing essential is left unstated.

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

  Parameters5/5

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

  Schema coverage is 100%, but the description adds crucial meaning: activity_id is 'an activity id, not a work package id' and comes from specific sibling tools, while reaction names must be used because 'Passing the emoji character itself is rejected.' These details prevent common invocation mistakes and exceed what the schema alone provides.

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

  Purpose5/5

  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: 'React to a work-package comment with an emoji, or take your reaction back.' It clearly distinguishes this toggle from sibling tools like add_work_package_comment and edit_work_package_comment, and reinforces that with explicit cross-references.

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

  Usage Guidelines5/5

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

  It provides explicit use-case guidance: 'Use this for the lightweight acknowledgement a comment does not deserve' and names alternatives: 'list_work_package_comments reads the thread and produces activity ids; add_work_package_comment says something in words when an emoji is not enough.' It also warns against blind retries, which is a key when-not-to-use pointer.

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

• update_meetingA
  5/5.0
  Behavior5/5

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

  Annotations already mark readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the write nature is known. The description adds substantial behavioral context beyond that: partial update semantics ("Only the parameters you pass are sent; omitted fields stay as they are"), participants replacement behavior ("a partial list silently uninvites everyone else"), closed-meeting restrictions, optimistic locking (409 conflict), and permission requirements. It even reveals upstream behavior ("no dedicated state endpoint upstream — this plain field is it") and return shape. 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.

  Conciseness5/5

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

  The description is well-structured with a clear first sentence, a practical "Use it to..." list, a note on return shape, and a "Pitfalls" section. It front-loads the core purpose, uses compact bullet-like semicolon-separated examples, and every sentence earns its place. Despite its length, it is dense with actionable information and avoids fluff.

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

  Completeness5/5

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

  Given the tool's complexity (8 parameters, including lifecycle state transitions and concurrency controls) and the presence of an output schema, the description is remarkably complete. It covers usage scenarios, pitfalls, permission requirements, concurrency behavior, return value shape (referencing get_meeting), and what operations are deliberately not supported. The output schema handles return values, so the description's mention of the return shape is appropriate context, not redundancy.

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

  Parameters5/5

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

  Schema description coverage is 100%, meaning every parameter already has a detailed schema description. However, the tool description adds further meaning beyond the schema: it explains the overall partial-update model (omitted fields unchanged), the significance of lock_version for concurrency control, the participants replacement pitfall, timezone requirements for start_time, and the "cannot be cleared" nuance for title. This enriches the agent's understanding beyond the schema alone.

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

  Purpose5/5

  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: "Change a meeting's title, time, place or invite list — or move its lifecycle state." It clearly distinguishes this from siblings like create_meeting, get_meeting, and delete_meeting by enumerating the mutable attributes and lifecycle states. The cross-references at the end explicitly name sibling tools, reinforcing differentiation.

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

  Usage Guidelines5/5

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

  The description provides explicit usage context: "Use it to reschedule..., to publish a draft..., to start or wrap up..." and gives concrete example invocations. It also states when not to use it (e.g., "moving a meeting to another project is deliberately not offered") and cross-references get_meeting, create_meeting, delete_meeting, and add_meeting_outcome for related operations. This is exemplary guidance.

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

• update_time_entryA
  5/5.0
  Behavior5/5

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

  Beyond annotations (readOnlyHint: false, etc.), the description discloses critical behaviors: partial update semantics ('only the parameters you pass are written'), lock_version handling and conflict errors rather than silent overwrites, and refusal to edit within closed cost-reporting periods. This adds substantial transparency beyond the structured annotations.

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

  Conciseness5/5

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

  The description is front-loaded with a clear purpose sentence, followed by usage, behavior, and cross-references in a logical order. Every sentence adds useful information; no filler or redundancy. Despite being long, it earns its space.

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

  Completeness5/5

  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 usefully cross-references log_time's return shape. It covers edge cases (concurrency, validation errors, uneditable fields) and provides all necessary operational context. No significant gaps remain.

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

  Parameters5/5

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

  The schema already has 100% coverage, but the description enriches it further: it clarifies the 'comment' empty-string behavior, explains 'activity' name resolution against the entry's own form, and clarifies that time_entry_id is not a work package id. This is additive value beyond the schema.

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

  Purpose5/5

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

  The description opens with 'Correct an existing time entry', a specific verb-resource pair that clearly distinguishes it from siblings like log_time (create) and delete_time_entry. It further clarifies the scope by listing everyday fixes (wrong duration, day, activity, comment), making the purpose unmistakable.

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

  Usage Guidelines5/5

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

  It gives explicit when-to-use guidance ('everyday fixes'), clearly states what is not editable (work package and project) with an alternative action ('delete the entry and log it again'), and provides cross-references to list_time_entries, delete_time_entry, and get_project_metadata. This is exemplary usage guidance.

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

• update_work_packageA
  5/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint false, destructiveHint false), the description discloses optimistic locking, null-clears-field semantics, omitted-parameters-left-alone, workflow validation, and 409 conflict details. It also states the return includes the new lock_version, going well beyond what annotations provide.

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

  Conciseness5/5

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

  The description is structured into purpose, use cases, return value, pitfalls, and data sources. Every sentence carries useful information; the length is justified by 18 parameters and complex concurrency semantics.

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

  Completeness5/5

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

  With a rich output schema and 18 parameters, the description covers all critical operational aspects: optimistic concurrency, null behavior, workflow validation, error handling, and source of identifiers/values. It is fully sufficient for an agent to invoke correctly.

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

  Parameters5/5

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

  Schema coverage is 100%, but the description adds essential global semantics: omitted parameters are untouched while null clears fields, and it explains the lock_version conflict window and the parent_id uniqueness as the only hierarchy tool. This adds meaning beyond the schema.

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

  Purpose5/5

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

  The description opens with 'Change any writable field of a work package' – a clear verb+resource statement. It then lists specific use cases (assign/unassign, status transitions, rescheduling) and explicitly contrasts with the old fragmented tooling, distinguishing it from siblings like create_work_package and delete_work_package.

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

  Usage Guidelines5/5

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

  The description explicitly directs when to use this tool: 'Use it to assign or unassign, move a status forward, re-schedule, re-parent...' It also provides cross-references: IDs come from get_work_package/list_work_packages, and values from get_project_metadata. It explains the 409 conflict retry behavior and when to re-read, offering clear guidance versus alternatives.

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