carrel

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

No annotations are provided, so the description carries the full disclosure burden. It does add genuinely useful behavior beyond schema: text targets return converted content inline with a 1 MiB cap, which tells the agent when to expect a payload versus a file on disk. However, it never says the tool writes an output file (only the schema's force/out_dir hints at it), nor what happens on unsupported or failed conversions, nor whether conversion is lossy — gaps that matter for a mutation tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the core action front-loaded and the return-value caveat immediately after. 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?

There is no output schema, so the description must cover return behavior — it does for text targets but says nothing about what non-text targets yield (presumably a written file path). Combined with no annotations and five parameters, an agent still lacks the write/destructive framing and failure-mode information needed. The 1 MiB cap is the one real addition over structured 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?

Schema description coverage is 100%, so the schema already documents all five parameters including the full target-type list, the overwrite behavior of force, and the default for out_dir — baseline 3 applies. The description adds no parameter-level detail beyond what the schema states; the 1 MiB cap is about the return value, not a parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — "Convert a file to another supported type" — which is unambiguous and distinct from all listed siblings (search, pack, inspect, diff, redact, etc.), none of which convert. It stops short of naming the boundary explicitly, but no sibling competes for this task.

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?

No explicit when-to-use or when-not guidance, and no alternatives are referenced. Usage is only implied by the clarity of the verb; an agent must infer that this is the tool for format transformation rather than reading it 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that a 'differ' result is data, never an error—a key non-obvious trait—but omits other important behaviors such as path resolution, permission requirements, and behavior when files are missing or modes are incompatible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences with zero waste. The core purpose is front-loaded, and the behavioral note follows immediately afterward.

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 four-parameter tool with no output schema and no annotations, the description covers the essential purpose and one important behavioral trait. However, it leaves gaps around mode semantics, error conditions, and the shape of the diff result that an agent would need for confident invocation.

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 75%, so the schema already describes a, b, and root. The description adds meaning to the mode parameter by listing the supported types (text/struct/pdf/image), which maps directly to the enum, but it does not explain 'auto' or how mode changes comparison behavior.

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 ('Compare two files') and enumerates the supported file types, which clearly distinguishes it from siblings like convert or redact. It does not explicitly name an alternative tool or scope boundary, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to choose this tool over siblings such as carrel_inspect or carrel_convert, nor any stated preconditions. Usage is implied by the verb 'Compare', but the description offers no exclusions or alternative routing.

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 disclosure burden. It implies a passive report but never states that it is read-only, that it performs no installs despite mentioning 'install hints,' whether it probes the network or filesystem, or how long it may take. Those are exactly the traits an agent needs when deciding whether this diagnostic is safe and cheap to call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence with no filler, and the most useful content (what the report contains) is stated up front. It reads as a noun-phrase fragment rather than a complete sentence, but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no input schema, no output schema, and no annotations, the description is the sole source of truth about the return value, and it does list the report's sections. However, it leaves open what 'per-command status' and the 'capability table' actually look like and whether the report is a prerequisite check for other carrel_* tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly adds no parameter discussion, avoiding noise.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource concretely ('Environment report') and enumerates its sections: external tools with versions or install hints, per-command status, and the capability table. An agent can infer this is a diagnostics/self-check tool, though the verb is nominal ('report') rather than an explicit action like 'check' or 'diagnose'. It does not explicitly contrast itself with siblings such as carrel_inspect or carrel_meta, which sound adjacent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this tool versus alternatives — nothing like 'run before other commands' or 'use when a command fails due to a missing external tool.' With siblings named inspect and meta, the absence of any differentiation leaves the agent to guess the intended trigger.

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

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

With no annotations, the description carries the full burden. It usefully discloses that extraction returns a confidence per field and that saving as desk meta fields is optional, but it does not explain permission requirements, overwrite behavior when saving, or what happens when fields cannot be extracted.

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 front-loaded sentence that efficiently states the core action, extracted fields, confidence behavior, and optional save. The long field enumeration is justified by the tool's purpose, though it could be structured more scannably.

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 extraction tool with no annotations and no output schema, the description covers the main purpose and optional save behavior. It still leaves important context unaddressed, including output format beyond per-field confidence, OCR and root behavior, profile/date-order effects, and sibling alternatives.

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 67%, so the schema already documents several parameters. The description adds meaning for the optional save behavior ('save them as desk meta fields'), but it does not clarify ocr, root, profile, date_order, or path semantics 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 uses a specific verb ('Extract') and resource ('vendor, invoice number, PO, dates, subtotal/tax/total, currency, IBAN and account last-4') from clearly named document types. It is easy to understand what the tool does, but it does not differentiate itself from siblings such as carrel_inspect or carrel_meta.

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 document types '(invoice, receipt, statement)' imply the intended context, and the optional save behavior is stated. However, there is no explicit guidance on when to use this tool versus alternatives like carrel_inspect, carrel_meta, or other sibling 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, the description must carry the full behavioral burden; it partly does by disclosing the return values (indexed/skipped/pruned counts) and the default root resolution. It never states that desk files themselves are not modified, that `prune` deletes index rows, whether runs are idempotent, or how expensive a full-root build is.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and scope; nothing irrelevant. Minor redundancy in 'under root (default: the whole root)' where the default restates the scope.

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 no-annotation, five-parameter mutation of on-disk index state with no output schema, the description covers the basics (default scope, return counts) but omits safety-relevant context such as what `prune` destroys and cost of a full build.

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 all five parameters are already documented in the schema; the description only restates the default root scope. It adds nothing about how `paths` interacts with `update` or about the `prune`/`ocr` trade-offs beyond the schema strings.

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?

Uses a specific verb pair ('Build or refresh') with a concrete resource ('the desk full-text index') and states the default scope ('the whole root'). This clearly separates it from carrel_search or carrel_pack, though it never names a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Build or refresh' implies a re-runnable setup step that search presumably depends on, so usage is inferable. But there is no explicit when-to-use, no when-not-to-use, and no mention of when to pass `paths`/`update` versus letting it walk the root.

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

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

With no annotations, the description carries the full burden. It usefully discloses the returned metadata fields, but does not state that the operation is read-only, whether it requires filesystem permissions, or what happens when deep/exiftool is unavailable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence lists the key return fields with zero wasted text. It is appropriately sized for a simple inspection tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Because there is no output schema, the description must describe returns, and it does so by enumerating the main metadata fields and per-type detail. It leaves out deep/exiftool behavior, which the schema covers, and omits any read-only safety statement, but is largely complete for this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so path, root, and deep are already documented in the schema. The description adds no parameter-specific semantics beyond the general metadata mention, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb-resource pair: retrieving metadata for one file, and enumerates the returned fields (type, size, mtime, sha256, mime, per-type detail). That clearly distinguishes it from bulk or search-oriented siblings, though it does not explicitly differentiate from carrel_meta.

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?

Usage is implied by 'Metadata for one file', so an agent can infer this is the per-file inspection tool. However, there is no explicit when-to-use guidance, no exclusions, and no named alternative such as carrel_meta or carrel_search.

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 does convey that the attachments action writes files into a directory and that the threads action consumes either a file or a directory, which is useful behavior context. But it does not disclose overwrite/suffixing semantics (left to the force param), permissions, or whether the threads action writes anything or merely returns data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence naming the file type first, then the two modes. Efficient with no filler, though the two-mode construction is slightly dense and could be split for scanability.

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 five-parameter tool with no annotations or output schema, the description covers the core mode split and the differing path semantics. The remaining gap is what the threads action returns versus writes, which an agent might need to interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so the schema itself documents path, root, force, and out_dir well. The description only restates the path semantics already present in the schema and adds nothing about root, force, or out_dir. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource (eml/mbox email files) and two concrete operations (extract attachments, group messages into threads). It is clearly distinguishable from generic siblings like carrel_pack or carrel_convert, though it never names a sibling to differentiate against.

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 two listed behaviors implicitly map to the two enum actions, giving an agent a rough idea of when each mode applies. However, there is no explicit 'use this when...' guidance, no exclusions, and no pointer to any sibling tool for adjacent email tasks.

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 must carry the full behavioral burden, but it does not disclose permission requirements, whether set replaces or merges existing fields, what rm destroys, or what get/ls/find return. It names the operations but leaves the mutation and safety semantics opaque.

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 dense sentence that front-loads the core concept and then enumerates actions and condition examples with no wasted text. It is appropriately sized for a compact tool summary.

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 all action names for a multi-action tool and provides useful find-condition examples, while the detailed schema covers most parameters. However, because there are no annotations and no output schema, the missing behavioral context around mutation effects and return values leaves clear gaps.

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 88%, so the schema already documents nearly every parameter and the action enum. The description adds condition syntax examples such as vendor=acme and total>1000, but it does not add much beyond that for the remaining 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 clearly states a specific resource (typed key/value fields on desk files) and enumerates the operations: set, get, ls, rm, and find. It is easy to understand what the tool does, but it does not distinguish itself from likely siblings such as carrel_fields.

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 implies when each action is used, for example get/ls for reading fields and find for locating files by conditions, and gives condition examples. However, it offers no explicit when-not guidance or comparison with alternative sibling tools, leaving the agent to infer the right choice.

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 disclosure burden. It implies a persistent write to the desk db but says nothing about whether notes accumulate, whether duplicates are allowed, ordering of listed notes, permissions, or what either mode returns.

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?

One compact sentence with the primary write mode front-loaded ahead of the list mode, and no filler. It could be tightened only slightly by tying each clause to its action 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 two-mode tool with four parameters, no annotations, and no output schema, the description leaves too much unexplained: what listing returns, whether an empty result is possible, and how root resolution affects the note's identity are all unaddressed.

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 75%, so the schema already documents body, path, and root. The description reinforces body as free text and path as the owning file, but adds nothing about the root parameter or how action interacts with optional body.

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 ("Attach") and resource ("note") plus the target ("a file in the desk db") and a second mode ("list its notes"). It is clearly distinct from siblings like carrel_tag or carrel_search, though it never names an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The two modes map onto the action enum and the word "or" signals the choice, so usage is implied. However, there is no explicit guidance on when to add versus list, no prerequisites, and no comparison with closely related tools such as carrel_tag.

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 does disclose useful traits beyond the schema: which file types get text extracted (text, pdf, office, ebook) and that output combines a tree with contents. It omits whether the operation is read-only/non-destructive, how the byte budget affects output, and any permission or rate considerations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the action first and the output description second; no filler. It is arguably too terse for a 9-parameter tool, but nothing in it is wasted.

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 9-parameter tool with no annotations and no output schema, the description should explain the pack result structure and the read-only nature more fully. The file-type support and tree+text composition are covered, but an agent still can't tell what the returned document looks like or how the byte budget truncates 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?

Schema description coverage is 100%, so each of the 9 parameters is already documented, including the format enum, globs, max_bytes, and tree_only. The description adds only the high-level notion of tree-plus-text, which implies how tree_only and format relate, but nothing about query/root/top 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?

States a specific verb (pack) and resource (file or directory), plus the concrete output shape: file tree plus extracted text of supported files. It doesn't name or contrast any sibling (carrel_search, carrel_inspect, carrel_convert), so sibling differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this versus carrel_search (query-based retrieval), carrel_inspect, or carrel_convert. 'LLM-ready context' weakly implies the use case, but no exclusions, prerequisites, or alternatives are 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 full behavioral burden; 'Never writes' is a valuable explicit disclosure of non-mutation that substitutes for destructiveHint=false. It stops there, though: nothing about invalid-regex handling, size limits, encoding, or whether the source file is guaranteed untouched beyond the one-word claim.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the action and immediately followed by the two constraints that matter (no writes, no PDFs). Nothing is wasted and nothing needs reordering.

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 five-parameter, single-required-arg tool with a fully documented schema and no output schema, the description covers the essentials: what it returns, that it does not write, and what input types are rejected. Only edge-case behavior (bad regexes, large files, encoding) is left implicit, which is a minor gap here.

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 every parameter including the builtin pattern list and custom regex array is already documented. The description adds no meaning beyond the schema — it never distinguishes builtin from pattern or explains how the default replacement character behaves.

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 (redact) on a specific resource (a text file's contents) and notes the result is returned rather than persisted. The text-file restriction plus the PDF exclusion makes the scope unambiguous, though it never names a sibling tool as an alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'PDFs must go through the CLI (carrel redact FILE.pdf -o OUT.pdf)' is an explicit exclusion that routes the agent elsewhere with a concrete command. However, there is no positive guidance on when to choose this over e.g. carrel_convert or carrel_search, so the picture is clear but not complete.

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 that tagging mutates files (ref:<kind>:<value> tags) and that an alternate grouping output exists, which is useful, but it says nothing about permissions, whether tagging overwrites existing tags, or what the default non-link return looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the core action first and the optional behaviors after a semicolon. The long parenthetical of kinds is dense but the schema repeats it, so it is slightly redundant rather than wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter tool with no annotations and no output schema, the definition is minimal: it never describes the default result shape (matches per file), how tag/link/all interact, or what OCR enables behaviorally. Key interaction semantics are left to the schema defaults alone.

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 every parameter is already documented, including the kinds list and the patterns name=regex convention. The description only restates the kind enumeration already present in the schema, adding no syntax or default information beyond 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?

States a clear verb ('Find'), resource ('reference numbers'), an enumerated set of kinds, and scope ('in a file or directory'). It is distinguishable from siblings like carrel_search and carrel_fields, though it never names them, so the agent must infer the boundary itself.

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 two optional modes ('tag files' and 'group files by shared value') hint at when the extra flags matter, but there is no explicit guidance on when to choose this over carrel_search, carrel_fields, or carrel_tag, and no prerequisites or exclusions are 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?

No annotations exist, so the description bears the full disclosure burden. It usefully discloses the prerequisite index run and the on-disk store, but says nothing about result ordering/relevance, pagination behavior beyond the schema's limit, or what a result entry looks like. For a read-only search this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero filler; the operation comes first and the prerequisite second. Nothing could be removed without losing 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?

With no output schema and six parameters, the description should hint at the return shape or result structure, which it does not. Parameter coverage is fully handled by the schema and the prerequisite is covered, but the output side is left entirely to inference.

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 all six parameters including the meta filter syntax and root default are already documented in the schema. The description adds no extra parameter meaning (e.g. how query interacts with meta/tags), so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Full-text search the carrel desk index (.carrel/carrel.db)'. It also locates the resource precisely, which separates it from carrel_index (which builds the index) even though no sibling is named outright.

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 a concrete prerequisite — 'Requires a prior `carrel index` run' — which is the main condition that determines whether calling this tool works. It gives no explicit exclusions or named alternatives among the 14 siblings (e.g. carrel_refs, carrel_meta), so it falls short of the top bar.

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 indicates that add/rm mutate tags, but does not disclose permissions, reversibility, persistence, duplicate-tag behavior, or what find returns beyond the vague phrase 'files by tags'.

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 compact sentence with no wasted words, and the core operations are front-loaded. It communicates the tool's scope 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?

For a four-parameter mutation/query tool with no annotations and no output schema, the description is minimally adequate. It omits the root parameter, the all-of semantics for find, and any behavioral details about tag removal or lookup 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 75%, and the schema already documents path, root, tags, and the action enum. The description loosely maps actions to path/tags but adds no syntax, tag format, or root behavior beyond what the schema provides.

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 clear verb and resource: manage desk tags with add/rm/ls and find operations. It distinguishes the tag-management purpose from most siblings, though it does not explicitly contrast itself with carrel_search for tag-based lookup.

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 action list implies when each operation is appropriate, but there is no explicit guidance about when to use this tool instead of siblings such as carrel_search. Alternatives and exclusions are left to inference.

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