librarian_brief

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

With no annotations, the description carries the load and does disclose meaningful behavior: it scans existing PC content, reports relevance and gaps, honors registered librarian_guide guidance and shows its version, and explicitly handles the no-results case. It doesn't state cost/latency or that it is read-only, which keeps it short of a 5.

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?

Front-loaded with the START-OF-TASK BRIEF label and the call-first directive. A few conversational asides ('honestly', 'instead of hunting') add tone but little information, so it is slightly longer than necessary.

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?

An output schema exists, so return values needn't be spelled out, and the description covers trigger, scope, empty-case behavior, and both parameters. Missing only scope-of-search details and performance expectations for a tool that scans the whole PC.

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%, so the description must compensate, and it does: `task` is framed as the task/goal to pass, and `caller` is explicitly described as optional with the instruction to leave it empty. Only the `task` string format/verbosity expectation is left implicit.

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 action: pass a task, and the librarian reviews everything that already exists on this PC and reports what's relevant, reusable, and missing. That is distinguishable from siblings like librarian_locate or librarian_gap, though it doesn't explicitly contrast with them beyond the librarian_guide mention.

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 a clear trigger: 'Call this FIRST when beginning any non-trivial task.' It also sets expectations for the empty case ('If we have nothing, it says so plainly'), but never names when to prefer a sibling tool instead.

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