Search project records

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 well covered. The description adds behavioral context about deterministic lexical ranking and the optional semantic provider fallback behavior, which is genuinely useful. However, it doesn't describe token cost implications between modes beyond what the schema's 'view' parameter already hints at; the description doesn't independently disclose behavioral traits like pagination or result ordering beyond ranking mention.

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 well-formed sentences with zero wasted words. The first sentence states the scope precisely, the second explains the ranking mechanism. Every element contributes value.

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?

Description plus a comprehensive 100%-covered schema and rich annotations together fully specify the tool, including its hybrid/lexical modes, view choices, and record-family filtering. An output schema exists so return format doesn't need explaining. The only minor gap is that the description could hint at the breadth of use cases served by a cross-family search vs individual list tools like project_card_list.

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 all 5 parameters (mode, view, kinds, limit, query) are documented in the input schema itself. The description adds the deterministic-vs-semantic behavioral distinction for the 'mode' parameter, which complements the schema. However, it doesn't add further semantic guidance beyond what the schema already covers, so the baseline 3 is appropriate.

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

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

The description clearly states it searches multiple record types (cards, documentation, changelog, releases, durable memory) with a specific verb 'Search' plus resource. It distinguishes from siblings like project_card_list and project_doc_list by covering all record families, though it doesn't explicitly name an alternative for differentiated queries.

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 notes it 'Uses deterministic lexical ranking and an injected semantic provider when available,' giving context on how search behaves. It implicitly covers when to use (broad cross-family search) vs more specific list tools, but doesn't explicitly state when not to use it or name alternatives.

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