reading-room

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 usefully notes that the response includes a citation to the PDF page and clarifies accepted ID forms, but it does not explicitly mention read-only behavior, error handling, or what happens if the id is not found.

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 three sentences, front-loaded with the primary action, and every sentence adds value: retrieval purpose, accepted ID types with examples, and a key response trait. There is no redundancy or filler.

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 simple one-parameter fetch tool with no output schema and no annotations, the description is quite complete. It explains what the tool does, what inputs are valid, and one important return property (citation). It only lacks details on failure modes and full response shape, but these are less critical for a basic read 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 schema already describes the 'id' parameter at 100% coverage, but the tool description adds concrete examples (fauci_diary:entry:00026, anthony-s-fauci) and clarifies that concept IDs are also acceptable. This materially enhances understanding of the parameter beyond 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 description clearly states the primary action ('Retrieve the full text of one item by id'), specifying both the resource and scope. It distinguishes from search by focusing on single-item retrieval, though it does not explicitly contrast with sibling tools like get_concept or get_record.

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 provides clear context on when to use the tool: after a search, accepting either a doc_id or a concept id. It does not name alternatives or exclusions, but the explanation of accepted input types effectively guides selection among 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?

With no annotations, the description carries the burden. It discloses key behavior: returns frontmatter and body, rewrites cross-links to absolute URLs, and describes type-specific payloads. The verb 'Fetch' implies read-only, but it doesn't explicitly state non-modification or error handling.

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 sentences, front-loaded with the main action. The second and third sentences provide valuable details on output and accepted formats, but could be slightly trimmed. Every sentence earns its place without being verbose.

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 fully explains return content (frontmatter, body, type-specific fields), the link rewriting, and accepted input formats. This gives an agent enough context to invoke the tool correctly and understand its results.

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. The description adds concrete examples for the id parameter (slug, bundle path, person_id, display name), which is helpful but not essential beyond the schema. It does not add meaning to the type parameter beyond the schema's own description.

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 clearly states the tool fetches a concept document from the OKF bundle, with cross-links rewritten to absolute URLs. The title 'Read one concept in full' aligns, and the resource 'concept' distinguishes it from sibling tools like get_record or 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?

The description explains the purpose ('so the bundle can be traversed') and details accepted ID formats, implying when to use it. However, it does not explicitly mention alternatives or when not to use it, missing full exclusionary 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 burden of explaining behavior. It does disclose that the tool returns a full record with citation, participants, and surrounding conversation context, which is helpful. However, it does not mention potential limitations (e.g., whether the return is truncated), ordering of neighbouring messages, or any side effects, leaving some ambiguity for a read operation.

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 a single sentence that immediately states the primary action and key details, with no filler or repetition. It is front-loaded and efficiently communicates the essential 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?

For a simple one-parameter read tool with no output schema, the description provides sufficient context about what is returned (citation, participants, neighbouring messages). It does not explain the exact output format or ordering, but given the low complexity and the absence of an output schema, it covers the core expectations well.

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% and the doc_id parameter description already includes a specific example and origin (from search_records). The tool description adds minimal extra meaning beyond confirming that doc_id identifies the record; it does not introduce new parameter-related details.

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 clearly states the tool's purpose: retrieving a single communication in full by doc_id. It specifies the resource type (communication), the lookup key (doc_id), and what is included (citation, participants, neighbouring messages), effectively distinguishing it from siblings like search_records and fetch.

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 usage context is implied: you should have a doc_id from search_records. However, the description does not explicitly contrast this tool with alternatives like fetch or state when not to use it. The schema hint about the identifier origin provides some guidance but the description itself lacks explicit 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?

No annotations are provided, so the description carries full burden. It discloses return fields (id, title, excerpt, URL) and mentions fetching full text via an id. The read-only nature is implied, but the ambiguity of 'pass an id to fetch' (whether it refers to this tool or sibling) and the absence of any limits/error behavior keep it from 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?

Three concise sentences that front-load the purpose and return structure, then provide crucial sibling differentiation. No wasted words.

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 simple single-parameter search tool, the description adequately covers corpus scope, output fields, full-text access, and alternative tools. It lacks explicit mention of pagination or result limits, but given the simplicity and the absence of an output schema, it is reasonably 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 schema already describes 'query' as 'A question or phrase' (100% coverage), so the baseline is 3. The description adds contextual contrast with keyword mode and suggests query semantics, but it does not provide explicit syntax or clarify the id-passing mechanism, so it remains at baseline.

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 begins with a specific verb and resource: 'Search 18,094 communications from the U.S. Senate HSGAC COVID-19 releases.' It clearly differentiates itself from siblings by calling itself 'the standard search contract' and contrasting with search_records and search_pages.

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 explicitly states when to use this tool versus alternatives: standard queries, search_records for keyword/exact-string mode, and search_pages for raw OCR text and absence checks. This gives clear, actionable guidance on tool selection.

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 present, so the description bears the burden. It explains the tool's behavior: searches cross-linked concepts with provenance, matches names/aliases/descriptions, and implies that get_concept returns full details. It doesn't detail the return format or explicitly state read-only, but for a search tool this is adequate.

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 two sentences: the first defines the resource and scope, the second gives usage guidance and an alternative. Every sentence earns its place, with no redundancy.

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 simple search tool with three parameters and no output schema, the description provides enough context: what it searches, when to use it, which sibling to avoid, and where to get full results. The schema covers the parameter details, making this adequately 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 already covers all parameters (query, type, limit) with clear descriptions and examples, so the baseline is 3. The description adds only that it 'matches names, aliases and descriptions', which slightly enriches query semantics but doesn't materially extend parameter knowledge.

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 clearly states the tool searches the analysis layer for conceptual entities (people, organizations, topics, packages, etc.), which is a specific resource and verb. It also distinguishes itself from search_records by contrasting semantic search with string-matching 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?

The description explicitly says 'Use this when the question is who someone is, what a topic covers, or what a package contains' and contrasts with search_records. It also points to get_concept for full retrieval, giving clear when-to-use and alternative 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 provided, the description carries full burden for transparency. It discloses the literal matching behavior, the pre-segmentation scope, and imperfections due to OCR and page-spanning lines. It does not mention permissions or rate limits, but for a read-only search tool this is less critical and the description adds meaningful context.

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 three sentences, each serving a distinct purpose: stating functionality, defining the tool's role as the completeness layer, and providing usage guidance with caveats. No filler or redundancy, and the most important information is front-loaded.

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 context, limitations, and contrasts with siblings. However, it does not explicitly describe the return format (e.g., whether results include snippets or full page text). Given the absence of an output schema, adding a note about the response would make it complete. Still, the description is strong overall.

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 is 3. The description adds value by explaining that the query is literal, matches across whole pages, and that a miss has stronger evidentiary value. It also frames the query as operating on OCR text, enriching the schema's description. This merits a 4.

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 clearly states the tool performs a literal search over the OCR text of all 5,247 pages, with a specific verb and resource. It distinguishes itself from sibling tools by positioning itself as the 'completeness layer' and contrasting with search_records.

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 explicitly tells when to use this tool ('to settle whether a phrase appears in the corpus at all') and compares it to search_records, noting that a miss here is stronger evidence of absence. It also mentions limitations (OCR error, page-spanning lines) that qualify the 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?

With no annotations provided, the description carries the full disclosure burden. It clearly states 'Retrieval only: nothing is summarised, and a record's wording is the record's, not this server's,' which discloses the non-mutating, non-rephrasing nature of the operation. It also mentions the return fields, adding useful context beyond basic search behavior. It does not cover auth or rate limits, but for a retrieval tool this is adequate.

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 two sentences, front-loaded with the main purpose, and the second sentence adds essential behavioral context about retrieval-only processing. No redundant language or filler. Every 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?

For a search tool with four well-documented parameters and no output schema, the description adequately communicates the core purpose, return shape (speaker, date, grade, citation), and a key behavioral caveat (retrieval only, no summarization). It lacks an explicit note about pagination or result ordering, but those are not critical for basic invocation. The absence of output schema is mitigated by describing the return fields.

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 100% description coverage for all four parameters, so the schema already explains mode, limit, query, and include_quoted in detail. The tool description adds no parameter-specific information beyond what the schema provides (e.g., it does not mention the effect of mode or include_quoted). Therefore the baseline of 3 is appropriate.

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 clearly states the tool's function: 'Find communications matching a question or phrase.' It specifies the resource type ('communications'/'records') and details what is returned ('speaker, date, grade and a citation'). This distinguishes it from sibling tools like search_pages or search_concepts by focusing on records/communications.

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 implies usage by saying 'Find communications matching a question or phrase,' but it does not explicitly contrast with sibling tools like search_pages or search_concepts. There is no 'when to use this vs. that' guidance. The schema provides parameter-level guidance (e.g., mode), but tool-level alternatives are not mentioned.

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