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 explains that the response is grouped by operation type, the chosen id must be passed as audit_reason_id, and it details the error response format. It also implies user-specific availability via 'authenticated user may supply'. This covers the key behaviors an agent needs to know.

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 with no filler. The first sentence states the core purpose, the second gives the usage context, and the third describes the response format and error handling. It is front-loaded and every sentence adds value.

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, zero-parameter list tool with an output schema, the description is complete. It explains when to use it, what the response looks like, and how to handle errors. Nothing an agent needs to call it correctly is missing, and the sibling list confirms its unique role.

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 has zero parameters, and schema coverage is 100% by definition. There is nothing for the description to add about parameters. The baseline for 0 parameters is 4, and the description appropriately focuses on usage and response rather than parameter 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 returns audit-reason codes for the authenticated user, a specific resource and verb. It is unambiguously distinct from sibling tools that handle entries, searches, and definitions, so an agent can immediately understand its function.

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 instructs to use the tool before an audited delete_entry when LF_REQUIRE_AUDIT_REASON is involved, providing a concrete trigger. It does not explicitly state when not to use it, but the context and siblings make alternatives obvious, so the guidance is sufficient.

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 and delivers thoroughly. It discloses that this is a read-only scan, does not delete or merge, uses a two-pass approach (size probe then SHA-256 hashing only on collisions), is a single blocking call with no interim progress, and can be partial if folders are unreadable. It also details performance implications and error modes (not_found, auth_failed, not_a_folder). No contradictions with annotations since none exist.

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 long but every sentence earns its place. It is front-loaded with purpose and use case, then behavior, then sibling references, then a detailed return format. Structure uses paragraphs and a bullet-like listing of the output, making it scannable. No filler or redundancy; the length is proportionate to the tool's complexity.

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 4-parameter tool with an output schema, the description covers everything an agent needs: return structure (mode, groups, skipped, folders_unreadable), sorting (by wasted_bytes descending), partial-scan indicators (walk_truncated and folders_unreadable), and error responses. It even warns about performance for large max_entries. 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 the baseline is 3, but the description adds meaningful operational context: max_bytes defaults to LF_EDOC_MAX_BYTES (25 MB) and skipped entries are reported with a reason; max_entries is 'a stop, not a filter' that sets walk_truncated=true; recursive defaults to true. These clarifications help an agent make correct choices beyond what the schema states, justifying 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 opens with a precise verb and resource: 'Find byte-identical documents in a folder tree and group them.' It immediately gives the two canonical use cases ('are there duplicate files in here?' and 'how much space would deduping this folder recover?') and differentiates itself from siblings like compare_entries (similar-but-not-identical) and search tools. An agent can tell exactly what this tool does and what it does not do.

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 states when to use it ('Use this to answer...') and what not to do (read-only scan, must follow up with delete_entry/delete_edoc yourself). It names the sibling tools for alternatives: get_entry_by_path for resolving folder_id, get_document_edoc for downloading a specific copy, and compare_entries for similar-but-not-identical documents. This leaves no ambiguity about 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?

With no annotations, the description carries the full disclosure burden and meets it thoroughly: info sends no body, text comes wrapped in untrusted-content tags with paging reflecting raw text, and bytes are base64-inflated and often fail due to host caps. It also enumerates failure slugs, cap-refusal behavior, and OCR limitations, so an agent knows exactly what will happen at runtime.

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 long but information-dense, with short labeled mode paragraphs that are scannable and decision-oriented. The default mode (info) is front-loaded, and each paragraph earns its place by covering a distinct concern: mode selection, size limits, failure handling, and output quirks.

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 tool with no annotations, the description covers mode choice, content-type support, size caps, paging behavior, output wrapping, and all documented error slugs. The presence of a full input and output schema means remaining details are structural rather than missing from the 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?

Although the schema already documents every parameter, the description adds meaning the schema does not: byte_size can be null when Content-Length is omitted, pages and char_offset drive paging through truncated/next_char_offset, max_bytes can be raised after size_exceeds_cap, and each mode has distinct network and payload implications. This is precisely the parameter-level value a description should add.

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 a specific resource ('a document's edoc') and concrete operations (inspect, read as text, download as bytes), which is clear and action-oriented. It does not explicitly differentiate itself from the close sibling `laserfiche_document_get_text`, whose purpose may overlap with mode='text', and the term 'edoc' is not defined.

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 gives strong mode-selection guidance: info is the safe default, text is preferred for reading content, and bytes should generally be avoided. It also gives an explicit when-not-to-use with a concrete alternative for scans ('use search_content, which reads Laserfiche's OCR index'), but it never addresses the likely sibling `laserfiche_document_get_text`, leaving an agent to infer the boundary between those tools.

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 covers server-version constraints, extraction origin (OCR vs upstream), the wrapped text format with an untrusted-content notice, how char_count/truncated are computed, and the full error-return contract including which slugs map to which conditions. This is exemplary transparency 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 efficiently organized: purpose first, then usage guidance, then return/error contract. Every sentence contributes needed information—no filler, no repetition of schema content. The length is justified by the complexity of the server-version and error cases.

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 fully covers an agent's needs: what the tool returns, how the text is wrapped, what truncation means, what errors look like, and when the tool cannot be used. Even though an output schema signal exists, the description provides richer and more actionable information than a bare schema would.

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%, so the schema already documents both entry_id and max_chars. The description does not add parameter-specific semantics beyond what the schema states, but it does clarify how truncation affects the returned char_count/truncated fields. This meets the baseline but does not exceed 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 description opens with a specific verb and resource: 'Download a document's server-extracted text' and immediately scopes it to 'v2 servers only.' It also names the exact sibling alternative (get_document_edoc) that should be used for v1, so the tool is clearly distinguishable from similar document-reading 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?

The description explicitly says when to use this tool ('Use for reading a document's contents'), specifies the extraction pipeline context, and gives a concrete exclusion: v1 servers have no endpoint, so use get_document_edoc(mode="text") instead. This gives an agent clear routing logic for choosing between 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 full burden and does so thoroughly. It discloses exactly what is compared (five attributes plus optional fields), what is excluded (timestamps and entry IDs), how differences are categorized (only_left/only_right vs differences), and the exact success and error return shapes. It also explicitly states 'This tool never writes to Laserfiche', covering side effects.

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: purpose, usage, behavior, return format, and error handling are each in their own paragraph. Every sentence adds value, and it is long only because the tool is complex. No filler or repetition.

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 complexity, the description covers everything an agent needs: when to use, what it does, what it returns (including failure modes), what it excludes, and that it is non-destructive. Since no output schema is provided, the explicit return structure in the description is essential and is fully supplied.

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 context about the include_fields cost (two extra round-trips) and clarifies left/right roles, but most of this is already present in the schema descriptions. The description does not materially expand parameter meaning beyond what the schema already documents.

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 verb ('Diff') and a precise resource (two entries' attributes and template fields), then distinguishes itself from siblings by explicitly stating it replaces manual fetching and comparison. It lists concrete use cases and names the sibling tools it is not (get_entry, get_field_values, get_entry_by_path), so an agent can select it unambiguously.

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 explicit when-to-use guidance ('Use this instead of fetching both entries yourself and comparing by eye') and provides typical scenarios. It also tells when to set include_fields to false (skip round-trips) and points to alternative tools for inspecting a single entry or resolving a path. No ambiguity remains about 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?

With no annotations, the description carries the full behavioral disclosure burden. It does this by stating the success return type (`EntryDetail`) and a structured failure object with error slugs (`not_found`, `auth_failed`). It does not elaborate on permission requirements or the exact cause of `auth_failed`, but the fetch semantics and error contract provide solid transparency.

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 compact and well-structured: operation and returned fields first, then exclusions, then return/error behavior. Every sentence earns its place, and there is no fluff or unnecessary repetition.

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 an output schema, the description provides the essential context: what metadata is returned, what is deliberately not returned, and what the failure shape looks like. It leaves minor gaps around authentication prerequisites, but the `auth_failed` error slug already signals that authentication is a relevant concern.

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. It ties `entry_id` to the entry being fetched and echoes it in the error response, giving basic relational meaning, but it does not define where the ID comes from, its format beyond integer, or any special constraints. The single required integer parameter remains mostly self-explanatory from the schema title and tool name.

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?

Description opens with a specific verb and resource: 'Fetch one entry's metadata' and enumerates the fields returned (name, type, path, template, page count). It also explicitly distinguishes itself from sibling tools by saying it does NOT return field values or document content, which makes the tool's scope unambiguous.

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 gives clear negative usage guidance: it does not return field values or document contentprint, and names the tools to use for those needs. However, it does not explicitly position this tool against the other entry lookup/search siblings, such as by-path lookups or searches, so routing is strong but not fully exhaustive.

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 behavioral burden and discloses the failure response format and likely error slugs (`not_found`, `auth_failed`). It also clarifies that the returned `id` is meant to feed other tools, which defines the operational contract beyond what the schema shows.

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 compact and front-loaded: purpose, usage trigger, and return/error behavior each get one short, focused sentence. There is no filler or 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?

Given a single well-documented parameter and an output schema, the description fills the important gaps: when to use it, how the result connects to other tools, and how failures are represented. Nothing needed to invoke it correctly appears to be 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 schema already documents `full_path` with examples, backslash-separation, forward-slash acceptance, and case-insensitivity. The description only repeats the path style and adds downstream context rather than new parameter-level semantics.

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 verb and resource: 'Resolve a backslash-delimited Laserfiche path to its entry.' This clearly differentiates the tool from sibling lookup/search tools because it is keyed on exact path resolution rather than query or 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 explicitly says 'Use when the user refers to a location by path,' giving a clear trigger condition. It does not name alternative sibling tools to exclude, but the path-based condition and the downstream ID guidance make the intended context unambiguous.

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 delivers: it discloses the return shape, pagination via next_link, failure mode with structured error slugs, and even warns that server_error is common due to endpoint fragility. This goes well beyond typical descriptions.

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 appropriately dense for a complex query tool: purpose first, then usage routing, then syntax, then return/error behavior. Every sentence earns its place, and the structure makes the content easy to scan.

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 complexity and the presence of an output schema, the description covers everything an agent needs to invoke it correctly: when to use it, how to write queries, what results look like, and what happens on failure. It even points to an error contract document for edge cases.

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 meaningful query-language semantics beyond the schema, including clause types (name, content, field, folder scope), combining with & and |, and option syntax, which helps an agent construct valid queries rather than just understand the parameter shape.

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 verb and resource: 'Run a raw Laserfiche search query and return matching entries.' It clearly distinguishes itself from sibling tools by emphasizing 'raw' syntax, which separates it from search_natural, search_content, and search_by_name.

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: 'Use when you can already express the search in Laserfiche syntax.' It also names alternatives with clear conditions, such as preferring search_content for document content, search_natural for grammar/field name discovery, and search_by_name for simple name patterns.

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 meaningful work: it discloses that this is a convenience wrapper that builds the LF:Name/LF:LookIn clause, scopes matching to names only, and returns the same shape and error contract as search_entries. This goes beyond the schema, though it leaves auth/rate-limit details unstated.

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 short, purposeful paragraphs: a clear one-line summary, a compact explanation of the wrapper behavior and the search_content exclusion, and a brief note about return shape and error contract. No filler or redundant restatement of the 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?

The params are fully documented in the schema, an output schema exists, and the description covers behavior, limitations, and the main alternative. Some extra context about when to prefer laserfiche_entry_search or laserfiche_entry_search_natural would round it out, but 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 description coverage is 100%, so the schema already documents name_pattern, in_folder_path, and max_results thoroughly. The description adds the conceptual mapping to LF:Name and LF:LookIn clauses, but does not meaningfully explain parameter syntax beyond what the schema already provides; baseline 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 opens with a specific verb and resource: 'Find entries by name pattern, optionally scoped to a folder path.' It further distinguishes itself by stating it matches names only and pointing to search_content for contents, so an agent can separate it from the nearby search tools without ambiguity.

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 gives clear context: it is a convenience wrapper over search_entries and should be used for name-pattern matching. It explicitly says not to use it for document contents and names search_content as the alternative. It does not explicitly contrast with laserfiche_entry_search or laserfiche_entry_search_natural, but the name-pattern scope makes the intended use fairly clear.

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 are None, so the description carries the full burden — and it delivers. It discloses the data source (full-text index where OCR lives), the return shape, that it usually avoids downloads, and crucially flags hits[].text as untrusted document excerpts (a prompt-injection security notice). It also enumerates the failure modes and what triggers them. No contradictions with annotations since none are provided.

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 long but front-loaded with the core purpose and organized with bold section markers. Every sentence earns its place — query syntax, sibling routing, return format, security notice, and error modes are all load-bearing. It is denser than ideal, but justified for an 8-parameter tool with async behavior and multiple failure modes.

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, which lowers the burden, yet the description still covers purpose, usage triggers, sibling alternatives, query syntax, response shape, a security warning, and error handling with remediation. Nothing an agent needs to invoke 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 100% with strong per-parameter descriptions, so the baseline is 3. The description adds value on top by tying params to behavior: 'narrow with folder_path or raise timeout_seconds' connects those params to the search_timeout error path, and it explains how a bare query is wrapped and how hits_for_top controls excerpt fetching. This exceeds the schema-only 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 opens with a specific verb+resource: 'Search document text and return the passages that matched.' It then differentiates itself from siblings by name ('search_entries = raw query, no excerpts; search_by_name = filename patterns'), so an agent can pick it apart from the 21 sibling tools without opening 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?

Gives an explicit trigger condition ('Use this whenever the question is about what documents *say*'), names the follow-up tool (get_document_edoc with mode and pages), and provides concrete fallback paths for error modes (fall back to search_entries on async_search_unavailable, narrow with folder_path or raise timeout_seconds on search_timeout). This is explicit when-to-use and 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so well. It reveals the two modes, the auto-repair behavior on HTTP 400 (up to two repairs), the retry logic, and the `mode="error"` response containing every attempt. It also discloses the `pagination_unknown=true` flag for server caps. It doesn't explicitly state read-only status or auth requirements, but for a search tool these are largely implied and the disclosed repair/error behaviors are the critical transparency points.

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 detailed but efficiently structured: a one-line summary, a context sentence with sibling routing, then clear Mode A and Mode B sections with bold headers. Every sentence earns its place—no fluff or repetition. The use of bullets and explicit mode labels makes the two-mode behavior easy to parse quickly.

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 complexity (two modes, auto-repair, pagination uncertainty, folder scoping, and sibling relationships), the description is nearly complete. It covers mode behavior, repair reasons, error output shape, and the `pagination_unknown` edge case. The output schema exists, so return-value details don't need to be spelled out. Missing only minor edge-case details like non-400 failures, but the description provides strong coverage for an agent to call and interpret the tool 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?

The schema already documents all five parameters with 100% coverage, so the baseline is 3. The description adds meaningful interaction semantics beyond the schema: how omitting vs. providing `lf_query` switches modes, how `fuzzy` controls the wildcard-wrap repair, and how `folder_path` behaves differently in Mode A vs. Mode B. It also explains `max_results` clamping to `LF_MAX_PAGE_SIZE`, reinforcing the schema. This justifies a point above baseline, though not a 5 since some details like the exact repair mechanics are description-schema duplicative.

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 two-mode search tool with a clear verb and resource: 'Two-mode search: get query-authoring guidance, then execute with auto-repair.' It also distinguishes itself from siblings by explicitly naming when to prefer `search_content` for content questions and `search_entries` for queries the user can already write. This makes the tool's purpose and niche unambiguous.

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 the agent when to use this tool: when you need to author a Laserfiche query and don't know the server's templates or field names. It also gives clear exclusions and alternatives: 'For content questions, prefer `search_content`; for a query you can already write, `search_entries`.' Additionally, Mode A vs. Mode B usage is spelled out, so the agent knows exactly when to omit or provide `lf_query`.

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. It discloses the failure return format and hints at the information returned. It does not explicitly state that the operation is read-only, but 'list' strongly implies it; a small gap remains regarding any side effects or required permissions, though none are expected for a list 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?

Three short paragraphs with clear front-loading of purpose. Each sentence earns its place, and the alternative routing is compact. Slightly more verbose than strictly necessary, but nothing is 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?

Given the output schema and 100% param coverage, the description covers usage context, failure behavior, and sibling differentiation. It could be considered complete; the only minor omission is not explicitly stating pagination behavior beyond the schema, but that is already documented in the schema parameters.

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%, so the baseline is 3. The description adds minimal parameter-specific value beyond the schema, mentioning that field attributes are returned but not elaborating on skip/max_results/summary_only. It correctly stays out of the schema's way.

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 verb-resource pair ('List every field definition in the repository') and enumerates the returned attributes. It explicitly distinguishes itself from get_template_fields, naming the sibling alternative, so an agent can immediately tell which tool to use.

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 concrete guidance: use before authoring field queries/updates, and names the direct route for template-scoped fields. This is explicit when/when-not advice with a named alternative, leaving no ambiguity.

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 discloses the return structure (including each field's properties), the meaning of an empty list, and the error format. It doesn't explicitly state the operation is read-only, but the verb 'Read' implies that. It could add a note on permissions, but given the simplicity, this is solid.

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 purpose, then provides usage guidance, and finally details the return/error formats. Every sentence adds value, with no repetition or fluff. It is compact yet comprehensive.

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 tool, the description covers the operation, the return format, failure behavior, and a key edge case (empty list meaning no template). It is complete enough for an agent to call it correctly without additional context.

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. The description references 'on an entry', clarifying that entry_id identifies an entry, but it doesn't explain how to obtain the ID or any format details beyond the schema's integer type. For a single parameter, this is adequate but not exceptional, so a 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 states a specific action ('Read the template field values') with a clear resource ('on an entry'). It explicitly distinguishes itself from a key sibling (get_entry) by naming the alternative and its purpose, so an agent can immediately identify when this tool is appropriate.

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?

Provides explicit guidance on when to use this tool: for metadata questions, and when not to: for the entry's own properties, where get_entry is the alternative. This directly addresses the most likely confusion and leaves no ambiguity.

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 a strong job: it documents the success return keys (entries, total_count, next_link), conditional $count behavior, and failure mode with specific error slugs. It could add more about auth prerequisites or side-effect-free nature, but for a list operation the disclosed contract is substantive.

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 tight paragraphs each serve a distinct purpose: purpose, usage context, and return/error contract. No filler or repetition; the most important scoping 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?

Given an output schema exists and the schema covers all parameters, the description adds exactly the missing context: immediate-children scope, navigation workflow, pagination boundary via next_link, and failure shapes. An agent has everything needed to select and invoke this tool 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 description coverage is 100%, so the baseline applies. The schema already fully explains skip, folder_id, and max_results, including pagination behavior and root ID 1. The description reinforces folder_id usage but does not add significant parameter meaning 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?

States a specific verb ('list') and a precise scope ('immediate children (documents and subfolders) of a folder'). This clearly distinguishes the tool from siblings like laserfiche_entry_search and laserfiche_entry_get_by_path. The browse-style navigation framing further clarifies its role.

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?

Provides explicit when-to-use guidance: browse-style navigation from a known folder. It also names the sibling to use first for path resolution (get_entry_by_path) and redirects whole-repository searches to a search tool. This is model behavior for usage 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 the full burden. It discloses the item fields (linkTypeId, sourceLabel, targetLabel), notes that link types are directed, and gives the failure response shape. This is strong behavioral context for a read-only listing 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?

Three short sentences with no filler: purpose, usage context, and output/failure details. Information is front-loaded and 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?

Given the output schema exists and all parameters are fully described in the schema, the description supplies the missing context: when to use it, what fields the results contain, that link types are directed, and the error format. An agent has everything needed to invoke this 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?

The input schema covers all three parameters with clear descriptions and defaults, so the description does not need to add much. It does not meaningfully elaborate on skip, max_results, or summary_only beyond the schema, which meets the baseline for 100% schema coverage.

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: it lists entry-link type definitions on the repository. This clearly differentiates it from sibling definition-list tools like laserfiche_field_definition_list and laserfiche_tag_definition_list.

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 says to use this tool before set_links because a linkTypeId is needed from here. It does not enumerate when-not-to-use or compare against all alternatives, but the usage context is clear and actionable.

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 fully carries behavioral disclosure. It explicitly states that the tool never raises and never returns mode:"error", explains the fallback behavior when the /Repositories endpoint is disabled, and describes what healthy builds return. This goes well beyond a minimal listing tool description.

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 focused sentences: one states the purpose, one covers error/fallback behavior, and one covers healthy response. Every sentence adds information that matters for correct invocation, with no filler or repetition.

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 there are no parameters and an output schema exists, the description is complete: it explains the tool's scope, the unusual fallback scenario, and the healthy return behavior. An agent has everything needed to call and interpret the result 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?

The tool has zero parameters, so there is no parameter semantics to document. The baseline for no-parameter tools is 4, and the description does not need to compensate for undocumented parameters.

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: it lists repositories reachable by the account. It also clearly differentiates from all sibling tools, which target entries, folders, fields, documents, or tasks rather than repositories. No ambiguity remains about what the tool does.

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 makes the basic use case obvious—list repositories—but does not explicitly say when to choose this tool over siblings or provide any exclusions. The fallback caveat is behavior-related, not usage guidance. Usage is implied rather than stated.

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 behavioral disclosure burden. It adds valuable context beyond the schema: item shape (`id`, `name`, `isSecurityTag`), that an empty listing is normal, and the error response format. It stops short of explaining pagination behavior, but the schema covers 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?

The description is compact and well-structured: purpose first, then usage guidance, then output and error expectations. Every sentence earns its place with no 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 read-only listing tool with an output schema and fully documented optional parameters, the description covers the essential context: when to use it, what results look like, an expected edge case, and failure behavior. Nothing critical 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 description coverage is 100%, and the parameter descriptions already explain `skip`, `max_results`, and `summary_only` well. The main description adds no extra parameter-level meaning, so 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 states a specific verb and resource: 'List every tag definition in the repository.' This clearly identifies the tool's function and differentiates it from sibling definition-listing tools such as field, template, and link definition lists.

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 tells the agent when to use this tool: before `set_tags`/`merge_tags`, because undefined tags are rejected. This is direct, actionable usage guidance that prevents a common failure mode.

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 and handles it excellently. It discloses the exact return payload fields, the error response shape, and the meaning of not_found (token expired or wrong server), giving the agent accurate expectations beyond the schema.

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 with the core purpose in the first sentence, followed by usage context and return details. Every sentence adds necessary information, and 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 single-parameter async status tool with a rich output schema, the description fully covers usage, alternatives, return payload, and error semantics. Nothing an agent needs to call and interpret this tool 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?

The schema already documents operation_token fully, so the baseline is 3. The description adds value by explaining the token originates from async tools and that a not_found error indicates token expiry or wrong server, enriching the parameter's operational meaning.

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 looks up status of an async operation by token, using a specific verb and resource. It also identifies the async tools that produce the token, distinguishing it from sibling tools like laserfiche_task_wait.

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 explains when to use this tool (check progress) versus the sibling wait_for_task tool (wait-until-done semantics). It also indicates which parent tools return operation_token, leaving no ambiguity about the appropriate calling context.

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 explains the immediate-return behavior at 0, blocking until terminal/deadline at >0, the added 'timed_out' field, and that errors mirror underlying tools. It doesn't mention auth or rate limits, but for a poll/wait tool these are less critical; overall it gives a solid behavioral picture.

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 extremely concise: three sentences, no wasted words, and the core purpose is front-loaded. Every sentence adds either behavioral distinction or usage routing. This is a model of efficient tool-description writing.

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 that an output schema exists (so return values are documented elsewhere), the description covers the essential behavioral context: the two modes, timeout semantics, and relationship to sibling tools. It might be slightly more explicit about when to prefer this over the individual task tools, but the description handles it well. Missing minor details like 'when not to use' are acceptable because the timeout mapping makes it obvious.

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 has 100% coverage with detailed descriptions for all three parameters, so the baseline is 3. The description adds minimal extra meaning—mostly restating that timeout_seconds=0 returns immediately and poll_interval_seconds is ignored at 0, which is already in the schema. It does usefully synthesize the two modes, but doesn't go beyond the schema significantly.

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 as 'Check or wait on an async operation' and explicitly distinguishes it from sibling tools by mapping timeout_seconds=0 to get_task_status semantics and >0 to wait_for_task semantics. This makes it easy for an agent to know exactly what this tool does and how it differs from laserfiche_task_get_status and laserfiche_task_wait.

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 guidance: use timeout_seconds=0 for single-poll behavior or >0 for blocking wait, and names the alternative tools whose semantics it mirrors. It also notes 'Same payloads and errors as the underlying tools,' covering error handling expectations. This is excellent when-to-use and when-not-to-use 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 the full burden of behavioral disclosure. It discloses that the tool blocks, that it returns the same payload as get_task_status plus a timed_out flag, and that on a failed poll it returns an error object with a slug. This covers the key behavioral traits (blocking, timeout, error handling) without contradicting any structured data. The description could mention that it is non-destructive, but the nature of 'wait' makes that obvious.

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 with zero filler. The opening sentence immediately states the core behavior, followed by usage guidance and return specifics. Every sentence earns its place, and the most important information is front-loaded. This is an exemplary structure for an MCP tool description.

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 output schema exists and the description covers purpose, usage, behavior, and parameter semantics, nothing an agent needs to call the tool correctly is missing. It explains the timeout behavior, the error mode, and the relationship to get_task_status. The tool is not overly complex, and the description is fully sufficient for an agent to decide when and how to use it.

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% coverage, so the baseline is 3, but the description adds meaningful context. For operation_token, it specifies that it comes from async tools like delete_entry, copy_entry, sometimes import_document. For timeout_seconds, it clarifies that on deadline the last status returns with timed_out=true. For poll_interval_seconds, it mentions the delay between checks and the lower bound. These enrich the schema without repeating it, so a 4 is warranted.

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 core action: 'Block until an async operation reaches a terminal state.' It specifies the resource (async operation) and the condition (terminal state), and differentiates from siblings by explicitly positioning itself as 'Preferred over manual polling' and referencing get_task_status. This is a specific verb+resource statement that leaves no ambiguity about the tool's purpose.

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 clear context for when to use the tool: 'Preferred over manual polling' and explains the return payload relative to get_task_status. It implies that get_task_status is a single-check alternative, but does not explicitly state 'use get_task_status when you only need one status check' or list other exclusions. Still, the guidance is actionable and points to the key distinction between blocking and non-blocking behavior.

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 carries the behavioral burden. It does disclose the failure return shape and a behavioral boundary (no field enumeration), but it omits other useful behavioral context such as auth/permission needs, rate limits, or side effects. The read-only nature is only implied by the word 'List'.

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 compact and front-loaded, with the purpose stated first and each subsequent sentence earning its place. The boundary, filter behavior, and failure-mode note are all relevant and formatted with backticks for scannability. There is no filler or 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?

With an output schema and fully documented parameters, the description is largely complete: it covers the output item shape, filtering behavior, the key limitation, and the failure format. The only notable gap is the misnamed alternative tool, which prevents fully reliable routing; otherwise this would merit a 5.

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%, so the baseline is 3. The description adds only a minor semantic ('filter to one') beyond the schema's existing parameter descriptions. It does not clarify skip, max_results, or summary_only beyond what the input schema already documents.

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 ('List template definitions') and immediately distinguishes itself from field enumeration by noting it does NOT enumerate fields. The mention of item fields (id, name, fieldCount) and template_name filtering further clarifies the tool's exact scope. It is clearly differentiated from laserfiche_template_field_list and other list 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?

The description gives an explicit when-not instruction: 'Does NOT enumerate a template's fields — use get_template_fields for that.' However, the named alternative does not match any sibling tool exactly (the correct sibling appears to be laserfiche_template_field_list), which weakens the routing guidance. It provides no guidance on choosing among other list tools, but the core exclusion is explicit.

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?

Although no annotations are provided, the description discloses the return structure and error handling. It mentions that on failure it returns an error mode with a slug and that 'invalid_template_name' includes a list of valid names. This provides useful behavioral context beyond the schema, such as the error format and the hint for resolving invalid names. However, it doesn't explicitly state if the operation is read-only or has side effects, but as a read operation, the error handling is a key transparency point.

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 concise and well-structured. It starts with the primary action, then provides usage context, then details the return structure and error handling in a clear list. Every sentence serves a purpose, and the key 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?

Given the tool's moderate complexity, the description covers the essential aspects: the single required parameter, the optional filter, the return structure, and error cases. The output schema is present, so return format details are already encoded. The description is complete for an agent to use the tool correctly without additional context.

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 provides descriptions for both parameters, covering their meaning (exact name, case-sensitivity, and how to discover names) and the optional flag. The description adds context on how the 'required_only' parameter affects the output (filters fields), which is implied in the schema but clarified here. Since schema coverage is 100%, the description adds marginal value but is still helpful.

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 ('Return'), a specific resource ('one template's fields'), and the scope ('with full metadata'). It clearly distinguishes itself from related list tools by focusing on a single template's fields, and it references a sibling (assign_template) to clarify its purpose in the workflow.

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: 'Use before assign_template to construct its fields argument.' It also explains that it replaces a more complex chain (list-templates + list-fields + cross-reference), providing clear guidance on the optimal usage context compared to alternatives.

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