sense

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), it discloses the key non-obvious behavior: memories matching the cue fire as recollections, are also queued for pending_recollections, and then go quiet for hours due to habituation, so repeating a cue yields nothing. It also states the return can be an empty list, which prevents an agent misreading an empty result as an error.

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 purpose and the alternative come first, then the behavioral consequences, so it is well front-loaded and each sentence carries information. It is dense for a single paragraph - the '(push mode)' tag and the habituation sentence could be tightened - but nothing is filler.

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 an 8-parameter, zero-required tool with no output schema, the description covers the trigger conditions, the minimum input requirement, the return value (fired recollections, often empty), and the cross-tool side effect on pending_recollections. Nothing an agent needs to call it correctly is missing.

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 the baseline is 3, but the description adds genuine semantics on top: at least one of text/location/biometrics/signals must be supplied, and the current time is always folded into the cue. That clarifies how the optional-looking fields combine, which the schema's zero required parameters does not convey.

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 opens with a specific verb and resource ('Report what is being perceived right now') and enumerates the accepted cue types (text, location, biometrics, raw signals). It also explicitly separates itself from the sibling 'recall' by naming search as the other mode, so an agent can route correctly without opening a 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?

It states the triggering condition concretely ('when the situation changes - arriving somewhere, a song playing, a notable phrase') and gives an explicit exclusion plus the alternative ('not to search; for searching use recall'). Both the when and the when-not are present.

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