guard_recall

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description still adds real value beyond them: match ranking ('match strength, then recency'), the trusted/agent provenance labels on hits, the 0–20 clamp with default 5, and the side effect that a tag filter silently excludes evidence rows. 'Does not create the store' partially restates the read-only hint but clarifies behavior on a missing store.

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 is front-loaded and the remaining sentences are dense with non-redundant facts. The phrasing is telegraphic and the keyword sentence is a run-on that takes a second read, but almost nothing is wasted.

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, zero-schema-coverage query tool, the description covers every parameter, the filtering interaction between tags and evidence rows, ranking and provenance of results, and the limit clamp. With an output schema present, return-shape documentation is correctly omitted.

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 0%, so the description carries the full burden and does so: it defines query keyword matching as case-insensitive substrings over text/cmd/digest with AND semantics, states that ev-NNNN keywords also match evidence ids, explains tags are AND and exclude tagless evidence rows, enumerates the type values, and notes evidence_id tolerates zero-padding (ev-7 == ev-0007). Every one of the six parameters gains meaning not present in the schema.

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 opening line gives a concrete verb+resource ('Search the retained journal and evidence window') plus a distinguishing constraint ('No embeddings'), so an agent knows exactly what class of retrieval this is. It does not explicitly contrast itself with the closely related siblings guard_journal and guard_evidence, which would have made the differentiation airtight.

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?

Usage is only implied through the parameter semantics — e.g. directing exact-id lookups to evidence_id, verify-run lookups to cmd, and category filtering to type. There is no explicit statement of when to pick this over guard_journal or guard_evidence, and no stated exclusions.

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