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

The description adds meaningful behavioral context beyond the annotations: it discloses the required API permission, the base64 encoding requirement for content, and the instance-level size limit retrieved from /api/v3/configuration. These details help the agent anticipate constraints and failure conditions. It does not contradict the annotations, which already signal a non-read-only, non-idempotent operation.

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

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

The description is concise and front-loaded with the core action, followed by permission and payload details. Every sentence contributes useful operational information, though the phrase 'content is the file bytes as base64' partially duplicates the schema description. Overall, it is efficient without being bloated.

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

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

For a mutation tool with no output schema, the description covers the key prerequisites: required permission, encoding of the file content, and the size limit. The input schema handles parameter requirements and defaults. The main gap is that it does not describe the expected response or error behavior, but this is not critical given the schema and annotations.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description restates that content is base64 and adds the size cap, but it does not provide substantial new meaning for id, fileName, or contentType beyond what the schema already says. This meets the baseline but does not rise above it.

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

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

The description opens with a specific verb and resource: 'Upload a file to a document.' This clearly identifies the action and target, and it is distinct from sibling tools like op_get_document and op_update_document, which describe different operations on documents. No ambiguity about what this tool does.

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

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

The description provides useful operational context, such as requiring the manage_documents permission and the attachment size cap. However, it does not explicitly state when to use this tool versus any alternative, nor does it mention exclusions or fallback options. Usage is implied by the tool's name and purpose rather than explicitly guided.

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

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

Annotations already indicate this is a mutating, non-idempotent operation. The description adds valuable behavioral detail beyond the annotations by disclosing that notifications are disabled unless notify=true, which is a meaningful side-effect control for an agent. It does not contradict any annotations.

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

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

The description is two short sentences with no filler. The primary action is front-loaded, and the notification caveat earns its place as essential side-effect information.

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

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

For a simple three-parameter tool, the description covers the core action, the comment format, and the notification behavior. It does not explain what the response contains or that repeated calls create duplicate comments, but the lack of an output schema and the straightforward nature of the operation keep this from being a major gap.

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

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

Schema description coverage is 67% and the description adds only limited meaning beyond the schema: it restates the notification default behavior and the markdown format already present in the schema. The id parameter remains minimally documented, but this is sufficient for a simple numeric identifier.

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

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

The description states a specific action ('Add a markdown comment') with a clear resource ('work package') and format ('markdown'). It is immediately distinguishable from sibling tools like op_update_work_package and op_create_work_package because the intent is to add a comment, not create or update the package itself.

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

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

The description clearly implies when to use the tool but does not explicitly state when not to or name alternatives. The sibling list helps infer that this tool is for commenting rather than creating or updating work packages, but the description itself provides no direct exclusion, alternative, or condition-based selection guidance.

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

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

Annotations already signal a mutating, non-idempotent, non-destructive operation; the description adds the useful fact that notifications are disabled by default unless notify=true, and that the created id is returned. It doesn't overclaim or contradict the annotations.

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

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

Three short sentences with no filler: purpose, return value + notification behavior, and usage context. The most important information is front-loaded.

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

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

For a 16-parameter creation tool with no output schema, the schema plus this description is sufficient: required fields, defaults, and value formats are in the schema, while the description supplies the missing result (created id) and default notification behavior. The tracked-project prerequisite supplies the operational context.

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

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

With 94% schema description coverage, the schema already documents all parameters in detail, so the description carries no extra parameter burden. It only reinforces the notify default already present in the schema.

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

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

States a specific action and resource — 'Create a work package' — and notes the return value. The prerequisite sentence ('Every change to a tracked project needs one of these before work starts') distinguishes creation from the update/comment siblings, so an agent can identify the right verb.

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

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

Says creation must precede changes to tracked projects, giving a concrete condition for when this tool is appropriate. It doesn't explicitly state that existing packages should go to op_update_work_package, so the when-not guidance is implied rather than named.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds value by disclosing what the fetch returns: title, markdown description, project, dates, and attachment details including file name, size, type, status, and download URL. This is useful behavioral context beyond the annotations.

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

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

A single, tightly written sentence that front-loads the core action and resource, then lists the returned content without wasted words. Every element earns its place.

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

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

For a simple read-by-id tool with one fully documented parameter, the description adequately covers return values by enumerating the main fields. No output schema exists, but the description supplies enough expectation-setting for an agent to invoke it correctly.

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

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

Schema coverage is 100% and the only parameter 'id' is already described as 'Document id.' The description does not add additional parameter-level meaning beyond confirming that the fetch targets one document by id, so baseline 3 is appropriate.

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

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

Description states a specific verb ('Fetch'), a specific resource ('one document'), and enumerates the returned fields. It clearly distinguishes from op_list_documents, which lists documents, and from mutation siblings like op_update_document.

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

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

The description clearly implies use when a single document's full detail is needed, and the sibling list tool is implicitly the alternative for browsing. It does not explicitly state when not to use it or name alternatives, but the context is clear enough.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior, so the description's burden is lower. It adds useful behavioral context beyond the schema, especially the hoursLedger caveat explaining that it is reported separately and never summed with spentTime. This goes beyond what annotations alone reveal.

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

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

The description is two sentences with no filler. The primary purpose and scope are stated first, and the only additional sentence is a specifically valuable behavioral nuance about hoursLedger. Every sentence earns its place.

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

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

For a one-parameter, read-only fetch tool, this is nearly complete: it states what the response will include and highlights an important edge case. There is no output schema, but the description names the major available fields. It does not cover not-found behavior or error cases, but those are less critical given the tool's simplicity and read-only annotations.

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

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

The schema fully documents the single required parameter 'id' as 'Work package id.', so the description does not need to repeat it. The description adds no extra semantic detail about the id beyond the schema, which aligns with the baseline score for 100% schema coverage.

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

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

The description uses a specific verb and resource: 'Fetch one work package in full detail.' It also enumerates the included content (custom fields, priority, version, time aggregates), which distinguishes it clearly from sibling list and mutation tools such as op_list_work_packages and op_update_work_package.

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

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

The description clearly implies the right usage context: use this tool when you need a single work package with full detail, as opposed to a list of packages. It does not explicitly name an alternative or state when not to use it, but the 'one' vs. 'list' framing gives an agent sufficient context.

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

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

The annotations already cover safety semantics with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the result is a list of comments and activities for a work package, but omits details like pagination, ordering, or permission requirements; it is consistent and adequate, though not rich.

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

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

The description is one front-loaded sentence with no filler. Every word contributes to identifying the operation and target resource.

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

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

For a simple one-parameter, read-only tool with comprehensive annotations, the description plus schema is largely sufficient. However, the lack of an output schema and absence of any usage/alternative guidance leave minor gaps about the exact return shape and when to choose this tool over related activities/list tools.

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

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

Schema coverage is 100%, and the schema already documents 'id' as 'Work package id.' The description references 'a work package,' aligning with the parameter, but does not add further semantics such as required-ness or any additional constraints, which is acceptable for a single parameter.

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

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

The description uses a clear verb ('List') and a specific resource ('comments and activities on a work package'), so an agent can identify the operation. It does not explicitly contrast with sibling tools such as op_list_time_entry_activities or op_list_work_packages, so it stops short of the highest sibling-differentiation standard.

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

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

There is no guidance on when to use this tool versus alternatives such as op_get_work_package, op_comment_work_package, or op_list_time_entry_activities. No conditions, exclusions, or prerequisites are stated, so the agent must infer usage from the name and resource.

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

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

Beyond the readOnly/idempotent annotations, the description adds meaningful behavioral facts: APIv3 has no create/delete for documents, documents are read/updated only, 'all' searches every project even when OPENPROJECT_PROJECT_ID is set, and results are newest first. This gives the agent a clear picture of what the operation will and will not do.

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

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

Three focused sentences: purpose/ordering, entity definition/API constraint, and the project special case. The most actionable information is front-loaded and no sentence is wasted.

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

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

For a read-only list operation, the description plus fully-documented schema covers purpose, ordering, scoping, and domain semantics. It does not describe the response shape, and there is no output schema, but the phrase 'list documents' plus the document definition makes the expected return sufficiently clear.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds at most the nuance that project:'all' overrides OPENPROJECT_PROJECT_ID and the 'newest first' default behavior, which is useful but not a major addition beyond the schema.

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

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

The description opens with a specific verb and resource: 'List documents (the Documents module), newest first.' It also clarifies the document entity and notes APIv3's read/update-only scope, which distinguishes it from sibling tools like op_get_document and op_update_document.

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

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

The description implies when to use the tool (to list documents) and provides useful domain constraints ('no document create or delete (UI-only), so documents are read and updated only'), but it never explicitly names alternatives such as op_get_document for a single document or op_update_document for modifications. Usage guidance is therefore mostly implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds that the return value is a list of priority names, but says nothing about ordering, completeness, or failure behavior; with the simple open-world list tool this is acceptable but not rich.

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

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

One sentence with no filler; the action, resource, and purpose are front-loaded. Every word earns its place.

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

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

For a no-parameter read-only list, the description tells the agent what it returns (names) and why it matters (valid value for create/update). It relies on sibling context to infer this means work-package priorities, but no other return details are essential for such a simple tool.

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

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

The tool has zero parameters and an empty input schema, so the baseline is 4; there is no parameter ambiguity for the description to resolve. The phrase 'priority names' clarifies the kind of value the caller will receive but is not parameter documentation.

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

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

The description uses a specific verb and resource: 'List priority names', and states its purpose ('so a create or update can name one that exists'). It clearly differentiates from sibling list tools because it is the only one exposing priority values.

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

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

The description explicitly frames when the tool is useful: before a create or update that needs a valid priority name. It does not name alternatives or exclusions, but the context is clear enough for an agent to select it over status/project/type list siblings.

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive. The description adds behavioral value by stating the result is scoped to what the API user can see and that results are paginated through pageSize and offset.

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

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

Two short sentences with the core action and scope first, followed by pagination. Every sentence earns its place and no redundant wording appears.

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

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

For a simple, read-only list operation with rich annotations, the description covers purpose, user-visible scope, included data, and pagination. It doesn't describe the response shape, but the absence of an output schema is mitigated by the simplicity and by 'with their identifiers.'

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

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

The input schema already provides 100% parameter coverage, including defaults for offset (0) and pageSize (200). The description only restates that pagination is controlled by these parameters, adding no new semantic detail beyond the schema.

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

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

The description uses the specific verb 'List' with the resource 'OpenProject projects' and defines the scope ('visible to the API user') and included data ('identifiers'). This clearly distinguishes it from the work-package and document siblings since the resource is named explicitly.

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

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

It clearly states the operation's context: listing projects visible to the current API user with pagination. It doesn't explicitly name alternatives or conditions, but no sibling is another project-list operation, so the lack of exclusions is not a material gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds that the tool enumerates all status names, but does not disclose details such as pagination, ordering, or whether the return format includes more than names. Still, it adds modest context beyond the annotations.

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

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

The description is a single, compact sentence that leads with the action and resource, then justifies the purpose. Every word contributes value and there is no redundancy.

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

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

For a zero-parameter read-only list tool, the description fully communicates what the agent will get (status names) and why it matters (valid values for updates). The annotations cover safety and mutability, so no further context is necessary.

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

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

The tool has zero parameters, and schema coverage is trivially complete. With no parameters to document, a baseline of 4 is appropriate; the description correctly focuses on the tool's output rather than input.

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

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

The description states a specific verb ('List') and resource ('every status name'), and clarifies the purpose ('so an update can name one that exists'). This distinguishes it from sibling tools like op_list_types or op_list_priorities, which target different enumerations.

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

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

The description implies a clear usage context: call this before performing an update that needs a valid status name. It does not explicitly name alternatives or exclusions, but the use case is evident and the tool name itself disambiguates from sibling list tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds genuinely useful behavioral detail about the return format: both ISO-8601 duration and decimal hours plus a total, which helps the agent understand output without an output schema. This goes 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.

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

Two short sentences with no fluff. The core purpose is front-loaded, and the second sentence adds practical value about the returned format. Every word earns its place.

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

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

Given that this is a simple read-only list tool with a fully described schema and read-only annotations, the description is almost complete. It explains the key return-value detail that would otherwise be missing without an output schema. It does not mention pagination or default project behavior, but those are partially covered by parameter descriptions and are minor for this tool.

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

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

Schema description coverage is 100%, so all six parameters are already documented. The description does not add meaning beyond what the schema provides, but it also does not need to. It mentions no parameter-specific behavior, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the action ('List') and the resource ('logged time'). It is distinct enough from siblings like op_log_time (which creates time entries) and op_list_time_entry_activities (which lists activity types). However, it could more explicitly say 'time entries' and distinguish itself as the read-only listing sibling.

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

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

There is no explicit guidance about when to use this tool versus alternatives, such as op_log_time for creating entries or op_list_time_entry_activities for activity types. The description simply states what it does without addressing selection criteria, filter combinations, or exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the purpose context ('Needed to log time') but no additional behavioral details such as pagination, ordering, or configuration nature; this is acceptable for a simple list tool.

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

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

Two short sentences with no redundancy. The core action and output are stated first, and the purpose sentence adds essential context for when the tool matters.

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

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

For a parameterless list tool with strong annotations, the description adequately states what is returned (activity categories with ids) and why it is needed. No output schema exists, but the return content is simple and sufficiently described.

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

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

The tool takes zero parameters and schema description coverage is 100%, so there are no parameter semantics for the description to clarify. With no parameters, the baseline is 4.

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

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

The description uses a specific verb ('List') and resource ('time-entry activity categories'), names example categories, and states the output includes ids. It clearly differentiates from sibling op_list_activities by scoping to time-entry activity categories needed for logging time.

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

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

The description clearly implies this tool should be used before logging time, specifically to choose the right category for op_log_time. It does not explicitly name alternatives or state when not to use it, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds modest context by saying results are scoped to a project and include names, but it does not disclose ordering, pagination, or behavior when project is omitted. No contradiction with annotations.

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

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

A single sentence with no filler; the verb and object are front-loaded and every word contributes. It is appropriately sized for a simple list operation.

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

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

For a one-parameter, no-output-schema list tool, the description captures the essential operation and return content, and annotations cover side-effect safety. Missing information about the project parameter's accepted identifier format and any behavior when no project is provided leaves a noticeable but not severe gap.

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

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

The single 'project' parameter has no schema description (0% coverage), and the description only says 'in a project,' leaving the value format and optionality unclear. The agent receives no information about whether to pass an ID, slug, or object, so the description does not compensate for the low schema coverage.

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

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

The description uses the specific verb 'List' with the resource 'work package types' and narrows scope to 'a project.' Among siblings, this is clearly distinct from op_list_work_packages and other reference-data list tools. The phrase 'with their names' also sets an expectation about the response content.

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

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

No guidance is given about when to choose this tool over siblings like op_list_work_packages or op_list_activities, nor any conditions that would make it the appropriate choice. The only implied context is that the caller wants work package types, but exclusions and alternatives are absent.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. Beyond that, the description discloses the multi-stage fallback resolution order and the 'source' field that reports which list answered — behavior an agent genuinely needs to interpret why result sets differ. This adds meaningful context without contradicting the annotations.

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

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

Three sentences, each earning its place: the core function is front-loaded in the first sentence, the second explains the critical fallback behavior, and the third clarifies a response field. There is zero filler or redundancy.

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

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

For a single-optional-parameter read-only tool whose safety profile is covered by annotations, the description captures the essential complexity: the fallback order, restricted-key compatibility, and the source marker. The only gap is the full response shape, but no output schema exists and the description does reveal the id and source elements, making this near-complete.

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

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

Schema coverage is 100%; the input schema already documents the project parameter, its default (OPENPROJECT_PROJECT_ID), and the 'all' sentinel. The description's phrase 'the project's assignable users' echoes the schema rather than adding new meaning, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('List the principals that can own a work package, with their ids'), which cleanly differentiates it from the sibling list tools (op_list_projects, op_list_work_packages, op_list_types, op_list_statuses). The 'principals that can own a work package' framing is precise and not a generic user-listing tautology.

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

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

The fallback chain explanation ('Falls back from the project's assignable users to /principals to /users, so it works on a key that cannot read /api/v3/users') gives clear context on when this tool is the right choice — namely when credentials lack access to the users endpoint. However, it never names an alternative tool or an explicit when-not-to-use condition, so it stops short of a 5.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context beyond that: ordering by newest-id last, default status/project behavior, and the fact that project=all overrides OPENPROJECT_PROJECT_ID. There is no contradiction with annotations.

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

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

The description is two sentences and wastes no words. It front-loads the core action and ordering, then supplies the most important defaults and special cases in a compact, readable structure.

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

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

For a read-only list operation with all parameters optional and fully described in the schema, the description is complete enough to guide correct invocation. It covers defaults, allowed status values, cross-project behavior, and ordering; annotations cover safety, and the schema covers pagination/search parameters.

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

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

Schema coverage is 100%, so the parameters are already documented. The description adds value by clarifying that status=all "includes closed items" and that project=all searches across every project even when OPENPROJECT_PROJECT_ID is set, which goes beyond the schema's concise default-value notes.

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

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

The description opens with a specific verb and resource: "List work packages," which clearly identifies the operation. It further distinguishes the tool from siblings like op_get_work_package by implying a collection-level query and adds useful ordering/scoping details (newest-id last, default project, status filtering).

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

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

The description provides clear context for when to use the tool: it lists work packages with defaults for status and project, and explains special values like status=all and project=all. It does not explicitly mention alternatives such as op_get_work_package for single-resource retrieval, so it stops short of a full when/when-not comparison.

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

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

The description adds genuinely valuable behavior beyond the annotations: the entry is always attributed to the API key's own user because OpenProject makes that field read-only, and the result includes hoursLedger when the local ledger is installed, making double-logging visible at write time. This is exactly the kind of context (auth constraints, side-effect visibility) that annotations alone do not convey.

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

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

Four sentences, each earning its place: the core action, the hours format nuance, the attribution constraint, and the ledger side-effect. The hours-format sentence slightly duplicates the schema's hours description, but it is a critical calling detail worth front-loading. No filler or repetition of annotation flags.

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

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

For a 5-parameter write tool with no output schema, the description covers the most decision-relevant nuances: accepted hours formats, attribution limits, and the conditional hoursLedger field in the result. It stops short of describing the general return shape or failure behavior, but the coverage is well above the minimum viable level.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the hours format (decimal or ISO-8601) that the schema already documents, adding no new meaning for comment, spentOn, activity, or workPackage. The description neither compensates for a gap nor adds semantic depth beyond the schema.

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

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

The opening sentence "Log time against a work package" uses a specific verb and resource, clearly distinguishing this write operation from the sibling listing tool op_list_time_entries and from op_comment_work_package. An agent can determine what this tool does and what it is not without deep schema inspection.

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

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

The intended use is strongly implied by the name and first sentence, but the description never explicitly states when to choose this tool over an alternative (e.g., when to use op_list_time_entries to read existing entries, or op_list_time_entry_activities to resolve activity values). No exclusions or routing conditions are given, leaving usage to inference.

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

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

Annotations only declare readOnly=false, openWorld=true, idempotent=true, destructive=false. The description adds critical behavioral detail beyond those flags: the description field replaces the entire markdown body, concurrent edits are last-write-wins with no locking, and the {'raw': ...} form corrupts stored text while a plain string is the safe format. This is exactly the kind of context an agent needs before invoking the tool.

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

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

Three dense sentences, with the core action and scope front-loaded. Every sentence earns its place: the replacement semantics, the concurrency/locking caveat, and the serialization pitfall are all actionable and non-redundant with the schema or annotations.

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

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

For a three-parameter mutation tool with no output schema and simple annotations, the description covers the key hazards an agent must know: whole-body replacement, last-write-wins concurrency, and the correct string format for description. Nothing essential to calling the tool correctly is missing.

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

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

The schema already documents title and description with 67% coverage. The description adds value by clarifying that title and/or description can be updated and by warning that the description parameter must be a plain string, not the {'raw': ...} object used elsewhere. It does not add meaning for the id parameter or title max-length beyond what the schema already provides, so it stops short of a 5.

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

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

States a specific verb and resource ('Update a document') with a clear scope ('title and/or description'), and further clarifies that the description replaces the whole markdown body. It also contrasts documents with work packages, which distinguishes it from the sibling op_update_work_package even without reading that tool's schema.

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

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

The description gives clear operational context: it is for updating document title/description, and it explicitly notes that unlike work packages, documents have no lockVersion and are last-write-wins. This effectively warns against expecting optimistic locking and points to the work-package tool as the one that has it, though it stops short of explicitly naming the alternative tool for work-package edits.

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

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

Adds substantial behavioral context beyond annotations: automatic lockVersion handling, loud failure on concurrent edits, and notifications-off-by-default. These are non-obvious traits that prevent silent overwrites and surprise emails, going well beyond the structured hints 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.

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

Two tight sentences with purpose front-loaded. The second sentence packs two high-value behavioral details with no wasted words. Every clause earns its place.

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

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

For a 17-parameter update tool, the description is surprisingly complete: it covers the operation, concurrency behavior, and notification default. There is no output schema and no mention of the return value, but for an update call this is a minor gap since the schema already documents the inputs and the main risks are addressed.

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

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

Schema description coverage is 76%, and most parameters already carry good descriptions. The description adds a key semantic fact: lockVersion is fetched automatically, so callers should not supply it. This addresses a hidden parameter concern that the schema alone could not convey. The remaining undocumented parameters (id, dueDate, subject, startDate) are still inferable from their names and types.

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

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

States a specific verb and resource: 'Update a work package.' This clearly differentiates it from sibling tools like op_create_work_package, op_get_work_package, and op_comment_work_package. The concurrency note reinforces that this is the mutation entry point for existing work packages.

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

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

Usage context is implied by the verb 'Update' and the sibling set, but there is no explicit guidance about when to prefer this tool over op_create_work_package or op_comment_work_package. No exclusions or alternative-selection conditions are stated.

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