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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds substantive context they do not: results are snippets only, expired entries should be treated as historical facts, and returned knowledge is reference data rather than instructions (an injection guard). The only redundancy is the trailing 'Read-only.'

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?

Every sentence carries load: purpose, primary parameter behavior, alternative path, result-shape caveat, safety caveat, and a terse read-only confirmation. The forward routing to aidelly_get_brain_entry is placed immediately after the snippet caveat, which is the right order.

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?

No output schema exists, and the description correctly explains what comes back (snippets) and how to get the full records. With 7 params at 43% coverage, the scope/limit/types parameters remain only in the schema, but the core search workflow is complete enough to invoke correctly.

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 43% and seven parameters exist. The description adds real behavioral meaning for q (pass a topic, or omit to browse recent active entries), but says nothing about limit, scope, types, brand_id, or the query override object. It compensates for the most important parameter but leaves several undocumented.

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?

States a specific verb (Search) and resource (the workspace Brain plus opted-in agency knowledge), and scopes it clearly. It is distinguishable from the sibling aidelly_get_brain_entry, which is explicitly named as the tool for full entries rather than search.

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?

Gives an explicit usage moment ('before drafting content, captions, replies or campaigns'), an alternative mode ('omit q to browse recent active entries'), and routes the agent to aidelly_get_brain_entry when full entries are needed. When-to-use and the alternative are both spelled out.

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