execute_query

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

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

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

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

The description is front-loaded with the core action and then supplies only supporting details about sourcing query_id, server-side execution, and permission filtering. Every sentence contributes specific information without repetition.

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

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

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

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

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

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

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

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

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

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

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

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

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