better-bear

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context beyond this: it explains result ranking (title, then tag, then body), includes snippets for body matches, notes that locked/private notes may not match body searches and include 'locked: true' in results, and mentions the default limit (20). This compensates for the lack of output schema, though it doesn't detail error handling or pagination.

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 purpose in the first sentence, followed by ranking details, locked note behavior, and usage guidance. Each sentence adds distinct value without redundancy, and there is no wasted text. It efficiently covers key points in a compact form.

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 the tool's moderate complexity (search with ranking and locked note handling), no output schema, and rich annotations, the description is largely complete. It explains the return format (ranked notes with snippets and locked status) and behavioral nuances, though it lacks details on error cases or exact output structure. The annotations cover safety, so the description focuses on operational context, making it sufficient but not exhaustive.

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 fully documents all 4 parameters (query, limit, since, before). The description adds minimal parameter semantics beyond the schema—it only mentions the default limit of 20, which is partially covered in the schema ('default 20'). No additional syntax or format details are provided, so the baseline score of 3 is appropriate given the schema does the heavy lifting.

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 explicitly states 'Full-text search across Bear note titles, tags, and body content' with specific verbs ('search', 'returns') and resources ('Bear notes'), clearly distinguishing it from siblings like bear_list_notes or bear_get_note. It specifies the scope (titles, tags, body) and ranking mechanism (relevance with title matches first).

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 explicit guidance on when to use alternatives: 'If you can't find content you expect, try listing notes to check if the relevant note is locked.' This directly contrasts with bear_list_notes for locked notes. It also implicitly guides usage by detailing search behavior (e.g., locked notes may not match body searches), helping differentiate from other search tools like bear_context_search.

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