corpus

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

With no annotations, the description carries full behavioral burden and does so well. It discloses the truncation behavior, the metadata.truncated flag, and the citation rule about never presenting author-draft page numbers as journal pin cites. It also lists exact return fields, giving the agent a clear model of the tool's behavior.

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 well-structured and front-loaded with the primary action, followed by necessary return-field details, truncation caveats, and an Args section. Every sentence adds useful information without redundancy or fluff.

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 value structure, so the description need not restate that. The description adds essential context beyond the schema: truncation behavior, paging via fetch_document, and the citation-note caveat. For a single-parameter, read-style retrieval tool, this is fully complete.

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 input schema provides only the type 'string' with no description, and schema coverage is 0%. The description compensates by explaining that id is 'The document id from a search result,' which is the key semantic meaning needed to call the tool correctly. It could add more about expected format, but the source of the id is the critical information and it is present.

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 ('Retrieve') and resource ('full text of an Engelberg Center publication') and clarifies that the id must come from search. It also distinguishes itself from fetch_document, which handles truncated documents, and from search, which produces the id.

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 clearly indicates when to use this tool: after obtaining an id from search, to retrieve the full text. It also provides an explicit alternative for long documents: use fetch_document to page through truncated casebooks. It does not explicitly mention list_documents, but the context is sufficient for an agent to choose correctly.

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 full burden of behavioral disclosure. It transparently explains the paging mechanism (max_chunks per call, start_chunk offset, total_chunks and next_start_chunk in the response) and the metadata (including version and citation_note). It does not mention error handling or authentication, but for a read-only retrieval tool this is a strong disclosure of the key behaviors an agent needs to correctly manage long documents.

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 well-organized and efficient. It leads with the core purpose, then usage context, then paging, then return content, and finally parameter explanations in a clean list. Every sentence adds necessary information without repetition or filler. The structure makes it easy for an agent to scan and extract the important details.

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?

Given the tool's moderate complexity (paging, metadata, multiple parameters) and the existence of an output schema, the description covers all the essential aspects: how to start, how to continue reading via next_start_chunk, the nature of the returned data, and parameter semantics. It even includes guidance on citing drafts. Nothing an agent needs to successfully use this tool 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 input schema has zero parameter descriptions (schema coverage is 0%), so the description must compensate. It does so thoroughly in the Args section, explaining document_id (source and usage), start_chunk (zero-based offset and default), and max_chunks (default and maximum). This goes beyond the schema's bare defaults, giving the agent the semantic meaning needed to invoke the tool correctly.

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 action and resource: 'Retrieve the text of a specific Engelberg Center publication by document ID.' This clearly distinguishes fetch_document from its siblings: search() locates documents and list_documents() enumerates them, while this tool fetches content for a known ID. The purpose is unambiguous and differentiated.

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 states when to use the tool: 'Use after a search() call to get more context around a relevant chunk, or to read a paper in page order.' It also references the sibling list_documents() as a source of document_id, giving the agent a clear mental model of the workflow. No exclusions are needed because the tool has a focused role.

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 it delivers real behavioral detail: the seven publication-type categories, the meaning of working papers, the identity of the directors, and the fact that case-matched results include cited_case_matches whose counts signal depth of analysis. It does not state result ordering, limits, or pagination, which is the remaining gap.

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 types, then usage routing, then args — a sensible order with short paragraphs. Some redundancy between the body's type enumeration and the Args line, and the partial re-listing of types in Args is both duplicative and incomplete.

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, yet the description still explains the notable cited_case_matches field, which is above the bar. For a zero-required-parameter listing tool with no annotations, the only missing pieces are result ordering/limit behavior and the inconsistent publication_type enumeration.

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: each of the three parameters is documented with matching semantics ('partial match, case-insensitive') and cites_case gets worked examples plus a note on party-name vs. reporter-citation matching. The Args block, however, lists only four publication types while the body lists seven, leaving the enum range for publication_type inconsistent.

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 ('List publications from the Engelberg Center') and enumerates the corpus contents, so an agent knows exactly what domain it exposes. It also contrasts itself with the sibling 'search' tool, drawing a clean boundary between browsing and querying.

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 and the conditions that select this tool: 'Use this — not search — to answer what the corpus contains,' plus three concrete use cases (browse before searching, all work by an author, publications citing a case). The 'not search' exclusion is exactly the routing an agent needs.

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 are provided, so the description carries the full burden, and it does so well on the risky aspects: it explains the published vs. author_draft version split, warns that draft page numbers do NOT match journal pagination, enumerates locator kinds with their citation consequences, and mandates copying bluebook_citation verbatim. What it omits is operational behavior — result limits, pagination, query syntax, or empty-result behavior — which an agent also needs to invoke it reliably.

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 and cleanly organized: corpus scope, then when-to-use with alternatives, then return-field semantics. It is long, and since an output schema exists the field-by-field enumeration partly duplicates structured data; however the citation-fidelity and draft-pagination rules there are behavioral guidance the schema would not convey, so most of the length 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?

Given a single-parameter search with an output schema and three sibling tools, the description covers everything needed: what the corpus holds, when to prefer it over web search or siblings, and how to interpret and cite results safely. An agent can select and call this tool correctly without reading anything else.

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% and there is only one parameter, documented in the description's Args block as 'Natural language search query'. That is accurate but adds essentially nothing beyond the schema's own 'query: string' — no guidance on phrasing, operators, or length. Adequate, not enriching.

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+resource ('Search the published research corpus of the Engelberg Center') and scopes it concretely — named authors, ~300 works, enumerated subject domains. It also distinguishes itself from siblings by name (list_documents for catalog questions or cites_case lookups) and from web search.

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 routing rules: 'ALWAYS search this corpus when a question names one of these authors or involves IP law doctrine...'; use alongside web search rather than instead of it, with the reason given; and two named alternative paths (list_documents(cites_case=...) and list_documents for catalog questions). This is about as complete as when-to-use guidance gets.

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