search_issues

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions 'powerful filtering options' and gives examples, but it does not describe what fields are returned, pagination, sorting, or any limitations. Since there is no output schema, the agent is left without crucial information about the tool's behavior beyond the act of searching.

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 brief and front-loaded with the action, followed by three relevant examples. Every sentence earns its place; there is no filler or redundancy. It is a model of concise, informative writing.

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

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

The tool has moderate complexity (5 parameters) and full schema coverage, but lacks an output schema and annotations. The description provides examples but does not explain the response format or any important behavioral details (e.g., whether results are paginated, how limit works). It is adequate for basic use but leaves gaps that could affect correct invocation.

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

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

The input schema covers 100% of the parameters with descriptions, so the baseline is 3. The description's examples add some context for how the query parameter can be used (natural language queries), but it does not provide additional meaning for the other parameters beyond what the schema already states. The schema itself is sufficiently descriptive, including the 'me' tip for assigneeId.

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

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

The description clearly states the tool's function: 'Search for issues in Linear with powerful filtering options.' This uses a specific verb (search) and resource (issues in Linear). It is distinguishable from siblings like get_issue (retrieve a single issue) and get_my_issues (list current user's issues), though it doesn't explicitly differentiate itself from those tools.

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 examples provide concrete usage scenarios ('Find all high-priority bugs assigned to me', 'Show open issues in the Engineering team') that imply when to use this tool. However, it does not explicitly state when to use this versus sibling tools like get_my_issues or get_issue, nor does it mention any exclusions or prerequisites.

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