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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the description only needs to add matching semantics — and it does: spelling variants ('603 U.S. 369 = 603 US 369'), optional pincite or year, duplicate citations reported twice, results in order. It does not resolve the tension in its final clause, which implies the tool also surfaces citations the library lacks, even though the opening sentence says it reports matches to library authorities only.

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 tightly packed sentences, front-loaded with the core behavior and matching rules, with no filler. The trailing clause about finding citations the library does not have is the only part that costs clarity rather than adding it.

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?

There is no output schema, but the description covers the essentials an agent needs — ordering, duplicate handling, fuzzy matching on citation format, and pagination via the schema. It stops short of saying what a single reported mention contains (position in text, matched case reference), and leaves the whether-unmatched-citations-are-returned question open.

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 100%, with text, limit, and offset all documented in the schema, including that offset should use the previous call's nextOffset. The description adds nothing about these parameters, so the baseline of 3 applies.

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 precise verb and resource: scan draft text and report every place it cites an authority already in the library, returned in order. That framing immediately separates it from the sibling search_* / list_* tools, which retrieve library items rather than resolving citations inside a draft.

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 use case: check a draft against the research behind it. It does not name an alternative tool or state when not to use it, so an agent still has to infer that this is not a general citation parser for text unrelated to the library.

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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered; the description adds real behavioral context beyond that — previews are bounded, certain fields may be clipped, and 'preview limits never require a manual download', which tells the agent truncation is normal and not an error state. The remaining gap is that the readText/readMore references are not expanded or tied to a named sibling, leaving the follow-on path slightly ambiguous.

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?

Three sentences, front-loaded with what the tool returns, followed by the disambiguation and the follow-on routing. The first sentence is a long enumeration, but every clause names distinct returned content rather than padding, so there is little waste.

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 one-parameter read tool with full annotation coverage and no output schema, the description is nearly complete: it covers what is returned, that previews are bounded, and how to get more. The only shortfall is that 'readText' and 'readMore' are referenced without mapping to the actual sibling tools (read_library_text, get_source_text), which could cost an agent a step.

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?

There is a single parameter and schema coverage is 100%, with the schema itself stating it is the 'case guid from a search or list result'. The description adds no further semantics about the guid (no format hints or provenance beyond what the schema says), so the baseline 3 applies — the schema does the work here.

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 concrete resource ('One authority') and enumerates exactly what comes back: notes, analysis, saved quotations with pincites, projects, related-authority connections, and captured source text. It explicitly separates itself from search_cases/list_cases rows, which 'already carry a summary', so an agent can distinguish this read tool from its siblings 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 gives an explicit when ('when you need the whole note, the quotations, or those connections') and an explicit when-not ('not to identify a case', because search and list rows already carry a summary). It also routes to follow-on tools for full text ('readText') and for clipped fields ('readMore'), which is genuine alternative-selection guidance rather than implied usage.

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?

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the description's job is to add operational traits — and it does: results may be partial, clipping is signalled, nextOffset alone does not recover clipped tails, and no manual download is needed. It stops short of describing pagination/cursor semantics or ordering guarantees beyond 'most matching first' for query.

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?

Dense and front-loaded — the identity of the resource comes first, then routing advice — with no filler sentences. It is a single run-on paragraph of chained clauses, which costs some scannability for a six-parameter tool.

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?

With no output schema, the description carries the return-value burden and does it reasonably by signposting readText, readMore, nextOffset and matchedPassage.readMatch as the places to continue reading. The response envelope itself (field names, section object shape) is never laid out, which is the main residual 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 already 83%, yet the description adds genuine cross-parameter meaning the schema cannot: how outline, query, maxChars and offset compose, that query follows the same phrase/shorthand/word-form rules as search_library, and that nextOffset does not cover clipped text. The limit parameter is not addressed in the description, but the schema covers it.

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 sentence names the exact resource (captured text of a statute, regulation, court rule, or opinion) and the ID provenance is spelled out (get_case capturedSources or a search_library source hit). It does not, however, distinguish itself from the sibling read_library_text, so an agent cannot tell from this text alone which text-reader to pick.

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?

Strong in-tool routing: outline for structure, query for 'the part about X', maxChars for an excerpt, offset to page, readText/readMore to finish clipped text. What is missing is sibling-level guidance — no explicit statement of when to use this instead of read_library_text or library_overview.

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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior beyond that: it is a cheap single-call operation and it functions as a capability probe for the rest of the toolset. What it does not add is anything about result size or shape, but the enumerated contents largely cover that.

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 first front-loads the returned contents and the second delivers the call-first directive and its justification, so each sentence earns its place.

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?

With no output schema, the description carries the burden of telling the agent what comes back, and it does so by enumerating the reported dimensions. For a zero-parameter inventory tool with strong annotations, nothing needed for correct invocation 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?

The tool takes no parameters, so there is no parameter semantics to explain and the baseline applies. The description correctly focuses its words on the output inventory instead of inventing input guidance.

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 (this library) and enumerates exactly what the tool reports: authority count, projects, tags, courts, captured source text volume, and snapshot age. That level of specificity distinguishes it from siblings like search_library and read_library_text, which operate on contents rather than describing the inventory.

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?

"Call this first. It costs one call and tells you which of the other tools can actually reach what you are after" gives explicit ordering advice and a concrete reason (cheap capability discovery) that steers the agent away from blind searching. It stops short of naming a specific sibling or a scenario where you would skip it, so it isn't full when/when-not 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine context beyond that: offset-based paging and the fact that each row carries a one-line summary drawn from the user's own notes, which shapes how results should be presented.

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-loads the core claim (everything, no filter needed) and keeps to three sentences. The mid-sentence list 'what is in here, how big is it, summarise all of it' is slightly loose but still earns its place as usage framing.

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?

No output schema exists, and the description compensates by stating that rows carry a one-line summary and that results page through offset. For a six-parameter, zero-required read tool with full schema coverage, that covers what an agent needs to call it correctly.

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 schema already documents every parameter including the sort enum and the limit maximum. The description restates the narrowing options and the '"none"' sentinel for unfiled projects, but adds little syntax or format detail beyond what the schema supplies — baseline 3 applies.

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 — enumerate every authority in the library — and explicitly positions itself as the enumeration entry point ('This is how you enumerate the library'), which separates it from search_cases, search_library, and list_project_cases.

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 usage context ('what is in here, how big is it, summarise all of it') and notes that no query or filter is required, so the agent knows this is the browse-all path. It does not explicitly name search_cases or list_project_cases as the alternatives for narrowed lookups, so the when-not is left implicit.

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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds a real coverage boundary beyond annotations: items with no project association are silently absent from results, which prevents a false 'no results means none exist' inference. It does not discuss result volume or pagination behavior, keeping 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?

Two sentences, zero waste. The primary scope is front-loaded and the sibling routing constraint follows, with no restatement of the title or schema.

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 filtered list tool with full schema coverage, the description supplies scope, id sourcing, and the coverage gap. The only minor omission is what the list entries contain (title, year, citation fields) and the nextOffset cursor, which are implied only indirectly via the offset parameter description.

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 sort/limit/offset/projectId semantics are already documented, giving a baseline of 3. The description adds provenance the schema lacks — that projectId values must be obtained from library_overview — which is meaningful guidance for the only required parameter.

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 resource and scope: 'Every authority filed under one project or matter,' matching the title's verb+resource. It also distinguishes itself from the sibling list_cases by reserving project-less authorities for that tool, so an agent can choose correctly 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?

It explicitly routes the agent: project ids come from library_overview, and authorities filed under no project are unreachable here and must go through list_cases with project "none". Both the when-to-use source and the when-not-to-use alternative are named.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantial behavior: paging with a byte budget that can return less than requested, hasMore scoped only to the selected target, ranges as UTF-16 code units with an exclusive end, an excerpt not being a complete document, and the stale_cursor recovery path. These are exactly the traits an agent needs to paginate correctly and to interpret hasMore without over-inferring completeness.

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 dense but front-loaded, opening with what is read and the small-page model before moving to cursor sourcing and edge cases. Each sentence carries operational content, though the stacked clauses about ranges, hasMore, and stale_cursor make the middle slightly hard to parse on first read.

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 two-parameter read-only pagination tool with no output schema, the description covers cursor provenance, paging limits, range units, the completeness caveat, and the error path, which is enough to call it correctly. It stops short of naming the fields a page object returns or how nextCall differs from cursor, so a little context is left implicit.

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 would be 3, but the description adds real meaning: the cursor is only obtainable from another tool's read object and must be copied unchanged across calls, and page size is expressed in UTF-16 code units that truncate at UTF-16 boundaries rather than characters. It also clarifies that maxChars is a cap the byte budget may undercut, which the schema alone 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 gives a concrete verb ('read') plus the specific resource types it returns (source text, notes, analysis, quotations, relationship notes) and states the paged delivery model. It does not explicitly distinguish itself from the sibling get_source_text or search_library, so the agent must infer that this tool is the cursor-driven continuation path rather than the initial retrieval.

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 tells the agent exactly where the cursor comes from (a readText/readMatch/readMore/nextCall object returned by another tool), when to advance (follow nextCall when more text is needed), and how to recover (repeat the original discovery call on stale_cursor). What is missing is an explicit statement of when to choose this over get_source_text or search_library, so the guidance is operational but not fully differentiating.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavior beyond that: it always targets the *newest* export rather than a caller-chosen one, and it is a legitimate recovery path after a load failure. It stops short of saying what happens when no export exists or whether in-memory state is replaced.

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, zero filler, with the core action ('re-read the newest export') front-loaded before the situational guidance. Every clause earns its place.

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 zero-param, fully annotated, no-output-schema tool, the description covers what it does and when to invoke it. The remaining gap — failure modes such as 'no export present' or whether it replaces a currently loaded snapshot — is minor but would be useful for a recovery-oriented 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?

The tool takes zero parameters, so the baseline is 4 and the schema has nothing for the description to disambiguate. The description correctly implies selection is implicit (newest export) rather than parameterized, which is consistent with the empty 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?

States a specific verb+resource: 'Re-read the newest export from disk,' which tells the agent exactly what data is loaded and from where. It is clearly distinct from the read/search siblings (read_library_text, search_cases, get_source_text) because it refreshes an already-loaded export rather than querying new content, though it never names an alternative explicitly.

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 two concrete triggers: after the user exports a fresh backup, and as a retry after a load failure. That is clear when-to-use coverage; only explicit when-not guidance is absent, which is low-impact for a zero-parameter refresh tool with no overlapping 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?

Annotations already declare read-only, idempotent, closed-world behavior, and the description still adds real detail not in them: ranking spans title/citation/tags/notes/analysis/quote text, each result carries a summary plus the matched passage, and quoted phrases are required rather than preferred. It stops short of anything about result caps beyond the schema or failure modes, so it is strong rather than exhaustive.

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-loads what the tool returns and how ranking works, then layers the query syntax, the filtering advice, and the offset/list_cases fallback. Every sentence carries operational information; none is filler or restatement of the title.

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-required search tool with no output schema, the description covers query syntax, filtering, pagination, and what each result contains, so an agent can call it and interpret results without guessing. Nothing essential 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 baseline would be 3, but the description adds meaning the schema does not: multi-word and quoted-phrase query semantics, citation spelling normalization (603 U.S. 369 = 603 US 369), and the guidance to express court filters via the court parameter rather than free text. That materially improves how an agent fills query, court, and 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 ("Find saved authorities") and immediately qualifies the ranking behavior across named fields. It distinguishes itself from siblings by explaining that results usually let you skip get_case and by routing whole-library walks to list_cases.

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 explicit when-to guidance: omit query to browse, page with offset, narrow by project/court/tag instead of putting a court name in the query, and use list_cases to walk the entire library. It also names the alternative (get_case) and when it is unnecessary, plus the when-not for wildcards.

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?

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior, and the description adds genuine value beyond them: ranking semantics, the one-row-per-authority collapse with alsoMatched children, offset-based paging, and browse-vs-rank mode when query is omitted. With no output schema, this result-shape disclosure matters, though per-row fields and the presence of a nextOffset field are only implied.

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?

Three dense sentences, front-loaded with the core identity before the when-to-use rationale and the result/ paging shape. Every clause carries information; nothing is filler despite the em-dash-heavy style.

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 search tool with no output schema and fully documented parameters, the description supplies what structured data cannot: ranking behavior, row grouping, and pagination. It could go one step further by naming the fields each row returns or clarifying the nextOffset response field it references only indirectly.

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 every parameter is already documented, and the description largely restates it — verbatim quoted phrases, omitting query to browse, paging with offset. The baseline of 3 is appropriate; the description adds emphasis but no new syntax or constraint information.

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: a single ranked search spanning saved authorities, saved quotations, and captured source text. It names the scope of corpora covered and distinguishes itself from narrower siblings like search_cases and search_quotes by emphasizing the union across all three kinds.

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?

"Start here when you do not already know which of those holds the answer" gives a clear selection condition, and the note that captured source text is otherwise reachable only by a known document id justifies the tool's niche. It stops short of explicitly routing the agent to search_cases or search_quotes when the kind is already known.

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?

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds value the annotations cannot: results are ranked, and each hit carries the passage, its source authority, and a pincite — important since there is no output schema. It stops short of describing result ordering or pagination flow, which the schema partly covers.

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 core action, then usage rule, then the verbatim tip, then the sibling redirect. No sentence restates the schema or wastes 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 three-parameter, zero-required search tool with full schema coverage and no output schema, the description covers scope, selection criteria, query-matching behavior, and what each result returns. Nothing an agent needs in order 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 a real semantic not present in the schema: quoted phrases are matched verbatim. That meaningfully changes how an agent should construct the query string, going beyond the schema's "Language to find".

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 ("Search the text of every saved quotation"), adds the ranking behavior, and explicitly distinguishes itself from search_library by scope. An agent can tell immediately that this covers only user-saved quotations, not the full library.

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 selection rule ("when the user wants language to quote rather than an authority to cite") and names the alternative tool with the condition that selects it (full text of opinions/statutes → search_library). It also supplies a search-strategy tip: quoting a phrase forces verbatim matching.

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