better-bear

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

The description adds valuable behavioral context beyond what annotations provide: it explains that the tool 'adds new notes, updates changed notes, and removes notes that no longer qualify (tag removed, trashed, etc.)' and 'regenerates the index.' While annotations cover idempotency and non-destructiveness, the description clarifies the specific sync behavior and qualification criteria, though it doesn't mention rate limits or authentication needs.

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 efficiently structured with three sentences: the first explains the core functionality, the second specifies scope limitations, and the third provides usage triggers. Every sentence adds value without redundancy, making it front-loaded and appropriately sized for the tool's complexity.

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 (sync operation with qualification logic), rich annotations (idempotent, non-destructive), and full parameter schema coverage, the description is largely complete. It explains what qualifies notes for sync, directory scope, and usage triggers. However, without an output schema, it doesn't describe return values (e.g., sync statistics), leaving a minor 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 description doesn't explicitly mention the 'force' parameter, but with 100% schema description coverage (the schema fully documents the parameter), the baseline is 3. The description implies the tool performs incremental sync by default, which aligns with the 'force' parameter enabling full re-sync, but doesn't add specific details beyond what the schema provides.

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 specific action ('sync qualifying Bear notes to the local context library') and distinguishes it from siblings by specifying it only touches the bear/ directory while leaving external/ and inbox/ untouched. It explicitly differentiates from tools like bear_context_add, bear_context_import, and bear_sync by focusing on synchronization with qualification criteria.

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 usage guidance: 'Call this when the user asks to sync, refresh, or update their context.' This gives clear triggers for when to use this tool versus alternatives like bear_context_add (for adding specific notes) or bear_context_import (for importing external content).

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