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

Since no annotations were provided, the description must carry the full behavioral burden. It explicitly states the types of grounded answers returned (WHAT / WHERE file:line / TOOLS / NEXT), which dictates the expected output structure to the AI.

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 description is overly verbose and academic. While the information is highly valuable, the structure is dense and lacks efficient phrasing, sacrificing conciseness for exhaustive coverage.

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?

Despite its length, the description is highly complete. It covers the scope, return formats, usage rationale, and parameter details, leaving very little ambiguous for the agent.

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 provide all value. It defines the optional 'caller' parameter, advising the user to leave it empty if not needed, adding necessary semantic context beyond the schema's types.

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 tool's purpose is exceptionally clear: to answer questions about the PC's entire system corpus. It explicitly outlines the scope (catalog, tools, machine map, etc.), immediately distinguishing it from general knowledge search or external models.

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?

The description provides explicit usage instructions, stating that AI sessions must use this tool instead of guessing or calling premium models. This is the strongest possible guidance for directing agent workflow.

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

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.

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

With no annotations, the description carries the full burden. It usefully discloses the semantic shape of the result (a dependency/blast-radius graph), but says nothing about traversal depth (direct vs transitive), result size, pagination, or cost on large entries, which matters for a graph query whose output schema the agent cannot preview.

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?

Four short sentences, front-loaded with the purpose and the 'what breaks' framing before usage and parameters. The only redundancy is the paired 'what breaks if I change X' / 'blast radius' phrasings, which reinforce rather than pad.

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 need not be described, and the read-style lookup has no destructive semantics to disclose. Purpose, trigger condition, and both parameters are covered; only traversal scope and edge-case behavior are missing, which is a minor gap for a 2-parameter query tool.

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 must define both parameters — and it does: `entry_id` is explained with a concrete example ('payments-module'), and `caller` is labeled as an optional label to leave empty. It stops short of stating the id format or what happens with an unknown id, so not a 5.

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 and resource ('show what depends on / connects to a catalog entry id') and glosses the meaning as the 'what breaks if I change X' graph. The sibling relationship is made explicit ('use after librarian_locate returns an [entry]'), so an agent can separate it from locate/brief without opening any 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 clear sequencing: call it after librarian_locate has produced an entry, in order to see that entry's blast radius. It also advises leaving `caller` empty. There is no explicit when-not guidance (e.g. what to use instead for forward dependencies or for full impact reports), which keeps it at 4.

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

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

No annotations, so the description carries the full burden and does substantial work: it discloses statefulness, the multi-turn expectation, the ASK: protocol, and — most valuably — thread isolation ("workers do not see the coordinator's turns") and reset scoping ("reset clears only your own thread"). It does not address failure modes or latency, which is a minor gap rather than a blocker.

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?

Core purpose is front-loaded, but the text is cluttered with uppercase emphasis, awkward hard line breaks, a duplicated article ("the the coordinator's"), and filler like "keep going until both sides agree the picture is complete." Trimmed, the same information would fit in two-thirds the space.

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 conversational tool with no annotations and a declared output schema, the description covers what an agent needs: how conversation state persists, how to reset, and who can see the thread. Return format is legitimately left to the output schema.

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 for two of three params: reset's exact effect and scope, and caller's meaning plus the "leave it empty" instruction, reinforced by the per-caller thread explanation. `message` is only implicitly defined as the turn content, so one parameter remains unstated.

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?

Specific verb+resource ("DISCUSS with the librarian") plus the defining trait: stateful multi-turn memory ("remembers your prior turns"). That implicitly separates it from one-shot siblings like librarian_ask or librarian_tell, but no sibling is named explicitly, so an agent still has to infer the boundary.

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 concrete usage contexts: verifying project understanding, asking about paths/tools, and answering the ASK: line back. Also gives the reset decision rule ("start a fresh discussion for a new topic") and encourages repeated trips. Missing an explicit when-not / named-alternative clause (e.g. "for a single fact, use librarian_ask instead").

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

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

No annotations, so the description carries the full behavioral burden and does substantial work: it says the report goes on a gap ledger, that every review re-hunts open gaps, and that still-unanswerable gaps escalate to the operator. That explains the downstream consequence of calling, which an agent otherwise couldn't infer. It stops short of saying whether duplicate gaps are merged or how quickly a gap is acted on.

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 core purpose and the librarian_tell escape hatch are front-loaded in the first sentence, and the ledger/escalation context follows usefully. The trailing `caller` note is appended after the behavioral explanation where it reads as an afterthought, and a stray line break splits the first sentence.

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 explained, and the lifecycle of a gap is well covered. What's missing is guidance on the two required parameters, which is the main thing an agent still needs in order to file a usable report.

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 must compensate, but it only addresses the optional `caller` parameter ('optional caller label; leave it empty'). The two required parameters, `subject` and `missing`, get no explanation of format, granularity, or what distinguishes a good report from a bad one.

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+resource ('REPORT a gap') and defines the gap as something the librarian was missing, with an explicit contrast to the sibling librarian_tell for when you do have the answer. An agent can distinguish this from librarian_tell and the other librarian_* tools without inspecting schemas.

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?

Explicitly names the alternative (librarian_tell) and the condition that selects it ('you don't have the answer yourself'). This is a clear when-to-use / when-to-use-something-else rule.

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

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

With no annotations, the description carries the full burden and does so: replace-on-write semantics, version bumping on every call, 6h expiry, reset-with-empty-text behavior, engine-side PII rejection, and hard filtering before the model sees excluded content. These are exactly the behavioral traits an agent needs before mutating shared state.

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 core purpose, then organized into per-parameter blocks that are easy to scan. The replace-on-write rule is stated twice (once in the intro, again at the end for `exclude`/`expect`), which is mild redundancy but defensible given the destructive implication.

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 need no explanation, and the description covers the remaining risk surface: scoping constraints, PII limits, expiry, reset, and cross-project bleed prevention. Nothing an agent needs in order to call this 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 0%, so the description must compensate and it does for every parameter: `text` (freeform, code/projects only, PII rejected), `exclude` (path prefixes/substrings/project names/catalog ids, hard-filtered, max 40 items at 200 chars, with a concrete example), `expect` (one line, <=500 chars, compared against worker reports), `reset`, and `caller`.

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 and resource ('register this session's intent') and explains its downstream effect on named siblings (librarian_brief / librarian_ask / librarian_discuss). An agent can distinguish this from the sibling tools without opening any 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?

Explicit about when: 'For the coordinating session, before delegating to workers' and 'Re-guide per phase.' It also names the alternatives that consume the guidance, so the agent knows this is the setup step rather than a query tool.

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

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

With no annotations provided, the description carries the behavioral burden and does well: it discloses that answers come from a fresh code index, that line numbers are current, and that a [changed] flag warns about recently edited files. It does not explicitly state read-only behavior or permission requirements, but those are strongly implied by 'find'.

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 description is front-loaded with the core purpose and usage guidance, and most sentences earn their place. It is slightly verbose in emphasizing exactness and currentness, but not wasteful.

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?

The description covers purpose, usage timing, query examples, freshness behavior, and the optional caller parameter. An output schema exists, so return format need not be explained, though scope and limits of the search are not fully specified.

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 must explain the parameters, and it does. It defines `query` as a natural-language question with useful examples and explains `caller` as an optional label to leave empty.

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 states a specific verb and resource: find the exact current location of code/config/catalog items, returning file:line. It clearly distinguishes the tool from grep-scanning, but does not explicitly differentiate it from the many librarian_* sibling tools.

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 gives a clear usage context: use this before grep-scanning the codebase, with example natural-language queries. It names grep as an alternative, but does not state when not to use this tool or how to choose among the librarian_* siblings.

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

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

No annotations exist, so the description carries the burden; it does disclose the return shape, ordering ('newest last') and a conditional field ('withheld-hit count (xN, only when exclusions filtered something)'), which is real behavioral value. However, an output schema is present, so much of that return detail is duplicated, and it says nothing about access scope, whether the log spans other sessions, or cost/pagination behavior beyond the limit parameter.

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?

A single sentence, front-loaded with the when-to-use context before the field enumeration, with no filler. It is dense and the mid-sentence field list is a bit crowded, but every clause carries information.

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?

The output schema covers return values and annotations are absent, so the main gaps are parameter behavior and operational scope. The unresolved `caller` semantics and the entirely undocumented `limit` leave enough ambiguity that an agent could mis-invoke or over-fetch, given this is a two-parameter tool with zero schema documentation.

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 must explain both parameters. It only addresses `caller`, and does so ambiguously -- '`caller` is an optional caller label; leave it empty' reads more like an output label than a filter, which leaves the agent unsure what setting it actually does. The `limit` parameter (default 30) is never mentioned at all.

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 states a concrete resource (this session's librarian interaction log) and its scope (workers + coordinator in the coordinating session), plus an explicit record shape ('one line per interaction, newest last, with caller, kind, ...'). It implicitly distinguishes itself from siblings like librarian_ask or librarian_status by framing it as a log/audit view for judging a worker report, though it never names an alternative.

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?

The opening clause 'For the coordinating session when judging a worker report' gives a clear activation context that an agent can match against a task. There are no exclusions or named alternatives, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the return content in concrete terms (catalog availability, per-category counts, index age), which implies a read-only diagnostic. However, it never states that the operation is non-mutating, whether it is cheap or expensive to call, or whether it requires a running index service — gaps that matter for a tool with zero annotation coverage.

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?

Two sentences, no filler. The capability statement is front-loaded and the parameter note trails it where it belongs. The parenthetical count list is dense but informative rather than redundant.

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 the description need not explain the response shape, yet it still previews the categories being counted, which helps the agent decide before calling. For a zero-required-parameter read tool this is close to complete; the only shortfall is the absent guidance on when this diagnostic should be preferred over the other librarian_* tools.

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: it explains that 'caller' is an optional caller label and explicitly instructs to leave it empty. That is more than the bare schema offers (only a default of ""). Minor gap: it does not say why the label exists or when supplying one would be useful.

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 names the resource ('librarian') and what the tool reports: catalog availability, index counts across six named categories, and index age. That is a specific, concrete purpose an agent can match to a need. It does not distinguish itself from siblings like librarian_guide or librarian_gap, which is the only missing element.

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?

There is no statement of when to call this versus the other nine librarian_* tools, nor any precondition or follow-up guidance. Only the parameter note ('leave it empty') gives any actionable direction. The status/health framing implies a diagnostic use case, but the agent must infer it.

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

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

With no annotations, the description does real work: it discloses that submissions are never rejected as irrelevant and are persisted for future sessions, which tells the agent this is a low-risk, always-succeeding write. It omits deduplication/overwrite behavior against existing knowledge and any size or auth constraints, keeping it below 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?

The leading imperative and the content inventory are front-loaded and the parenthetical '(never rejected as irrelevant)' is a tight clarifier. Mild redundancy between 'GIVE the librarian knowledge it doesn't have' and 'something ... it didn't know' costs it a point, but nothing is wasted overall.

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 need not be explained, and the acceptance/persistence semantics are covered. However, for a write tool with zero annotations and zero schema description coverage, the undefined `subject` parameter and the absence of any guidance on how entries interact with existing librarian knowledge leave a real gap.

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. It handles `caller` explicitly ('optional caller label; leave it empty') and effectively defines `info` through the enumeration of acceptable content, but `subject` — the second required parameter — is never explained, leaving the agent to guess whether it is a heading, a key, or a retrieval tag.

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 and resource ('GIVE the librarian knowledge') and immediately enumerates the kinds of payload it accepts (built things, discoveries, decisions, paths/tools, general context). That framing cleanly separates it from siblings like librarian_ask and librarian_locate, which retrieve rather than contribute.

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?

'Use whenever you know something the librarian got wrong or lacked' gives an explicit triggering condition, backed by the earlier inventory of acceptable content. It stops short of naming an alternative (e.g., librarian_session_log for routine logging) or saying when not to use it, so a 4 rather than 5.

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