hebbrix_remember

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

Annotations only establish write, non-idempotent, non-destructive semantics; the description adds the full async behavior: extraction polling up to 20s with a job_id result, the searchable flag meaning indexing is still pending, and knowledge-graph enrichment being asynchronous (~30s) and NOT covered by wait_for_index. It also discloses the return contract ({'id','status','searchable','graph_enrichment',...} or {'error'}) and warns against repeating writes, all consistent with idempotentHint=false, so there is no contradiction.

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?

Around 350 words, but every unit earns its place: purpose and trigger first, then one focused explanation per boolean flag, then async graph caveats, the multi-fact efficiency rule, and the return format. The density is justified by the tool's complexity (three behavioral flags, tracked jobs, async indexing), and there is no filler or repetition.

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?

For a six-parameter tool with async jobs, indexing, and graph enrichment, the description covers the full decision tree: when to call, which flags to set in which scenario, how to interpret searchable and graph_enrichment in the response, how to follow up via the documented poll tools, and when to avoid blocking serial writes. The only residual gaps are the semantics of tags and collection_id and an explicit cross-reference to hebbrix_remember_many, both minor against an output schema that already documents the return shape.

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 0%, and the description compensates for the three behavior-controlling booleans: extract (exact-store vs fact-extraction with job_id polling), wait_for_extraction (defer to hebbrix_extraction_status), and wait_for_index (searchable semantics, bulk-write advice). However, tags and collection_id are never mentioned in the description, so two of six parameters rely solely on their generated names.

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?

Opens with the crisp verb+resource pair 'Store a memory' and immediately broadens into a triggering condition ('user shares a fact, decision, or preference worth recalling later'). It differentiates itself from the obvious alternative (writing notes to files) and, via the multi-fact guidance, carves out when heavy extraction is preferred, so an agent can tell this apart from hebbrix_remember_many without opening either schema.

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 when-to-use trigger ('user shares a fact, decision, or preference worth recalling later') and an explicit precedence rule ('prefer it over writing notes to files'). It routes follow-up work to named siblings hebbrix_extraction_status(job_id) when wait_for_extraction=False and hebbrix_get(id) when searchable=false, and tells the agent not to repeat the write, preventing duplicate-memory mistakes.

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