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

There are no annotations, so the description must carry the behavioral burden. It does disclose that a local analysis plugin is run and that missing values are filled in, but it does not mention side effects such as metadata writes, permissions, response behavior, or whether the operation is reversible. This is a notable gap for a mutating 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?

One tight sentence that front-loads the action, target, and method. No wasted words or redundant 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?

The tool is simple with one optional parameter, and the description explains the operation and target clearly. However, without annotations or an output schema, it leaves out expected return values and potential side effects, so it is only minimally complete.

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

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

Schema description coverage is 100%, and the single parameter 'limit' is already documented in the schema. The description adds no additional parameter semantics, so the baseline score 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 action (fill in missing BPM/key), a specific resource (files lacking them), and the method (running the local detect_tempo/detect_key plugin). This clearly distinguishes it from sibling tools like list_tracks or scan_folder.

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 clearly indicates when to use this tool: for tracks that are missing BPM/key data. It does not explicitly name alternatives or exclusion criteria, but the context is clear enough for an agent to route to it appropriately.

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 disclose behavioral traits. It adds two meaningful behaviors not in the schema: preserves insertion order and skips duplicates. It implies mutation via 'append' but does not mention error handling or prerequisites, which would make it more complete.

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 one short sentence that front-loads the action and packs the key behavioral nuances into a parenthetical. Every word adds value, with no redundant or filler content.

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 2-parameter tool with no output schema, the description covers the core operation and the most important edge behaviors. It does not state that the crate must already exist or that track IDs must be valid, which are inferable but not explicit. This is adequate but not fully complete.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It says little beyond the parameter names themselves ('crate' and 'tracks'), adding no constraints on valid IDs, formats, or preconditions. This is a minimal addition over the raw 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 the specific verb 'append' with a clear resource ('tracks to a crate'), which unambiguously distinguishes this tool from siblings like crate_create and crate_list. The parenthetical about insertion order and duplicate skipping further refines the 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 context is clear: use this tool to append tracks to an existing crate. It does not explicitly name alternatives or state when not to use it, but the action is concrete enough for an agent to infer the appropriate scenario. No exclusions are provided, so it misses the 'explicit' bar for a 5.

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 behavioral burden. It explicitly discloses idempotency and the result of reusing a name, which is valuable behavioral information beyond the schema. It does not mention errors or permission requirements, but for this simple create operation the key behavior is covered.

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 sentence with a useful parenthetical. The core purpose is front-loaded, and the behavioral caveat is included without any wasted words.

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

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

The tool is simple: one required string parameter, no output schema, no nested objects. The description covers purpose, parameter semantics, and idempotent behavior. It does not explicitly describe the return value for a newly created crate, but the idempotent pattern makes that easy to infer.

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 has a single required 'name' string with no description (0% coverage). The description clarifies that 'name' is the crate's identifier and is central to the idempotent behavior, but it does not add format, length, or uniqueness constraints. It partially compensates for the missing schema description.

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

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

The description states a specific action — 'Create a named crate' — and adds an important distinguishing behavior: idempotency with the same name returning the existing id. This clearly separates it from siblings like crate_add and crate_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?

The description implies when to use the tool: when a named crate needs to be created. However, it does not explicitly discuss when not to use it or compare it with alternatives such as crate_add, so the routing burden falls on the tool name and 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?

There are no annotations, so the description carries the burden of revealing behavior. The verb 'List' implies a non-mutating read-only operation and the output content is identified, but no further behavioral detail (e.g., ordering, defaults, or response shape) is disclosed.

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 six-word sentence conveys the operation, resource, and output without waste. It is front-loaded and easy to parse.

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 simplicity (no parameters, no output schema, no nesting), the description is nearly complete. It states what is listed and what field is included; only minimal details like ordering or empty results are absent.

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 no parameters, so there is nothing for the description to elaborate on. The 100% schema coverage and zero-parameter signature make the input semantics complete.

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 ('List') and resource ('crates'), and specifies the returned information ('track counts'). This clearly distinguishes it from sibling tools like crate_add/crate_create (creation) and list_tracks (tracks).

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 guidance is given about when to use this tool versus alternatives such as list_tracks or stats. The intended use is implied only by the verb and tool name.

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 of disclosing behavior. It states that the learned model is wiped and that the summary returns to cold-start default, which is a meaningful side effect. However, it does not explicitly warn about irreversibility or data loss beyond the term 'wipe', nor does it mention any authorization requirements. The disclosure is adequate but not comprehensive.

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 concise sentence that front-loads the core action ('Wipe the learned model') and then qualifies the optional scope. There is no redundant information or fluff; every clause earns its place.

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

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

For a tool with one optional parameter and no output schema, the description covers the essential action, the optional parameter's effect, and a key side effect (summary reset). Given the simplicity of the tool, this is nearly complete. The only minor omission is an explicit statement about permanence, but 'wipe' strongly implies it, so the gap is small.

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

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

Schema coverage is 100% and the parameter description in the schema already documents 'forget_history' clearly. The description adds minimal extra meaning by linking it to 'sets/history' in prose. This meets the baseline of 3 for high schema coverage, with no significant additional clarification provided.

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 'wipe' on the resource 'learned model' and clarifies an optional scope (sets/history). It clearly distinguishes from siblings like learn_preferences (which adds) and preference_summary (which reads) without naming them explicitly, but the intent is 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?

There is no explicit guidance on when to use this tool versus alternatives. The description implies a reset action but does not state when it is appropriate, when it should be avoided, or what prerequisites exist. The mention of 'optionally also sets/history' gives a condition but not a full usage 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 explicitly states the tool is 'READ-ONLY' and 'Never writes your DJ libraries,' which is a key safety guarantee. It also notes that 'newer master.db is SQLCipher-encrypted and will be reported' (in the parameter description), disclosing a failure mode. This is strong behavioral transparency, though it does not specify whether the import appends, merges, or replaces existing data in the sets/history tables.

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

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

The description is two sentences long, with no wasted words. It front-loads the most critical constraint ('READ-ONLY') and immediately states the resource and sources. The second sentence reinforces the safety guarantee. This is exemplary conciseness and structure.

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 tool with three optional parameters and no output schema, the description covers the core purpose and safety profile adequately. It explains what it imports, from where, and that it is read-only. However, it omits details about the impact on existing data (e.g., whether it appends or overwrites entries in sets/history) and does not describe any progress or confirmation behavior. Given the schema coverage and simplicity, this is a minor gap, but the description could be more complete for an agent to fully anticipate side effects.

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, with every parameter described in the schema itself (source enum, serato_dirs, rekordbox_db). The tool description adds no additional parameter meaning beyond what the schema provides. Since the schema does the heavy lifting, the baseline of 3 is appropriate; the description does not compensate for any gaps because none exist.

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

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

The description clearly states the tool's function: 'READ-ONLY import of Rekordbox (master.db opened read-only) / Serato crates into sets/history tables.' It specifies the verb, resource, and source, and distinguishes itself by emphasizing it 'Never writes your DJ libraries.' This is precise and actionable, and it differentiates from siblings like import_rekordbox_xml by indicating it handles master.db and Serato crates rather than XML.

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

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

The description implies usage through the 'READ-ONLY' and 'Never writes' phrasing, suggesting it is safe to use without modifying source libraries. However, it does not explicitly mention when to use this over alternatives such as import_rekordbox_xml, nor does it state conditions like 'use this for master.db imports' or 'use XML for Rekordbox XML files.' The guidance is implicit rather than explicit, so it only partially fulfills this dimension.

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 behavioral burden, and it does add a useful safety note ('Read-only on the XML'). But it remains silent on equally important behaviors such as whether the import merges with or replaces existing sets, duplicate handling, or what happens with invalid/unsupported files.

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 dense sentence conveys the source format, version, data extracted, destination concept, and safety property, with no filler. The important resource and format details are 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?

For a single-parameter import tool, the description is complete enough to invoke correctly: it identifies the file source, path provenance, format constraints, and the high-level effect (importing content into sets). The absence of an output schema is slightly mitigated by the clarity of the import action, though merge/replacement semantics would make it fully complete.

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

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

The schema covers the only parameter (path) with its own detailed description including the menu path, so schema coverage is 100% and the baseline applies. The tool description does supplement with file-format/version constraints, but it does not need to re-document the parameter.

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

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

The description names a specific verb and resource: importing a Rekordbox 'Export Collection in xml' file. It goes further by stating the file format/version, the data it extracts (BPM/key/genre, cues, playlists), and the mapping 'playlists → sets', which clearly differentiates it from sibling tools like import_history or scan_folder.

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 context for use is clearly stated: use this when the user provides a Rekordbox collection XML export, with an explicit version constraint (6.3.0+, plaintext). However, it does not explicitly mention sibling alternatives or state when not to use it, so it stops short of full usage 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?

With no annotations, the description carries the full burden. It discloses that the learned model is explainable and one-click forgettable, which signals reversibility, but it does not state whether this operation overwrites an existing model, requires at least one imported set, or has any other side effects. Partial transparency, not complete.

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

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

The description is a single sentence that front-loads the action ('Learn a preference model'), then lists the specific model dimensions, and closes with two useful behavioral traits. Every clause earns its place; 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 zero-parameter tool with no output schema and no annotations, the description is moderately complete: it states the action, the source data, and a key property (forgettability). However, it omits prerequisites (e.g., must have imported sets first), what happens when a model already exists, and what the tool returns or indicates upon completion.

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

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

There are zero parameters, so the baseline is 4. The description adds meaningful context by identifying that the tool operates on previously imported sets, which is the implicit input. No schema details are needed.

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 ('Learn') with a clear resource ('preference model') and scope ('from imported sets'). It lists concrete model components (genre weights, ΔBPM, Camelot moves, energy steps, set shape), making the action unambiguous and distinguishing it from siblings like forget_preferences or preference_summary.

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 phrase 'from imported sets' implies the tool should be used after imports, but the description never explicitly states when to use it, when not to, or how it relates to alternatives like import_history, preference_summary, or forget_preferences. Usage is inferable but not articulated.

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 only lists filter criteria and does not disclose pagination behavior, default ordering, result shape, or any limits beyond the limit/offset parameters. It does not mention whether filters are combined as AND/OR or whether the query is fuzzy, which an agent would need to know for accurate invocation.

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, focused sentence that front-loads the primary action and lists all filter dimensions compactly. It avoids unnecessary detail and is easy to parse, though the comma-separated list could be slightly better structured for readability.

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 7 parameters, no output schema, and no annotations, the description leaves significant gaps: it does not state whether all filters are optional, how they combine (AND/OR), what the response contains (e.g., track IDs, metadata), or any default behavior. An agent cannot fully predict the tool's behavior beyond the filter inputs.

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 43% (only tags, query, camelot have descriptions). The description compensates by explicitly naming 'bpm range' (mapping to bpm_min/bpm_max), 'camelot code', 'genre tags', and 'limit/offset', giving meaning to otherwise undocumented parameters. It clarifies that the query matches title/artist/album. This adds value beyond the schema, though it does not detail accepted formats for camelot or tags.

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 action (search) and the resource (library), and enumerates the specific filter dimensions (title/artist/album, bpm range, camelot code, genre tags, limit/offset). This distinguishes it from siblings like track_detail or stats 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 implies this is the general search tool for library tracks, but it does not explicitly state when to prefer it over alternatives (e.g., 'for a single track use track_detail') or provide exclusions. Context from sibling names suggests the use case, but the description itself gives no explicit guidance.

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

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

With no annotations, the description carries the full burden and does disclose one behavioral trait: it falls back to defaults when history is insufficient. It also specifies the output is human-readable and in Chinese. However, it does not state whether the tool is read-only, what 'transition' means, or any side effects, leaving moderate gaps given zero annotation support.

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

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

The description is a single sentence that includes both the primary output and the fallback behavior without excess. It is slightly awkwardly phrased ('what you favour and how you transition') but remains efficient and front-loaded with the core purpose.

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

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

For a zero-parameter tool with no output schema or annotations, the description provides sufficient context: what is returned (a sentence), in what language (Chinese), and a key edge-case behavior (fallback). It does not explain where preferences come from or define 'transition', but given the low complexity and sibling names, this is adequately complete.

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

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

The tool has zero parameters, so parameter semantics are trivially complete. The description adds no parameter-related details because none exist, aligning with the baseline of 4 for no-parameter tools.

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 produces a human-readable Chinese sentence summarizing user preferences and transitions, which is distinct from sibling tools that manage (learn/forget/import) preferences. It is specific about the resource and output language, though it lacks an explicit verb like 'generates' and does not name a sibling for contrast.

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 explicit guidance on when to use this tool versus alternatives like learn_preferences or forget_preferences. The fallback note implies it is for display, but no conditions, exclusions, or alternative routing are provided. An agent would have to infer usage from the tool name.

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 of transparency. It discloses the incremental fingerprinting mechanism (size + mtime + head/tail 64KB hash) and that only changed files are re-read. This is meaningful behavioral detail beyond a generic scan, though it does not mention permissions or return behavior.

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

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

The description is a single concise sentence that front-loads the core purpose and then adds a necessary technical detail. It is efficient without wasting words, though the parenthetical fingerprint clause makes it slightly dense.

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 the core scanning behavior and provides useful internals, but it does not explain return values (no output schema), error cases, or the recursive parameter. For a tool with one undocumented parameter and no annotations, it leaves some context 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 coverage is only 50% because the recursive parameter lacks a schema description. The tool description does not compensate: it never explains the effect of recursive, which is a clear gap. The path parameter is partially covered by the schema, but the description adds no additional parameter 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 identifies the action ('Index/refresh') and resource ('a folder of audio files into the library'), and the fingerprint detail helps distinguish it from import-type siblings. However, it does not explicitly name or contrast any sibling tool, so it stops 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?

The phrase 'Index/refresh' implies a use case (keeping the library in sync with a folder), but the description gives no explicit guidance on when to choose this tool over alternatives like import_history or import_rekordbox_xml, nor does it state when not to use it.

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 burden of behavioral disclosure. It enumerates the specific pieces of information returned (tracks, missing BPM/key, crates, db size), which adds some transparency beyond a generic 'stats' label. However, it does not explicitly state that the operation is read-only or side-effect free, nor does it describe the output format, leaving some behavioral aspects implicit.

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 brief and front-loaded, delivering all key information in a single sentence. It is concise with no filler words. However, the telegraphic style ('How many tracks...') is slightly informal and could be clearer with a leading verb, though it remains effective.

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 zero parameters and no output schema, the description is the sole source of context. It lists the aggregated metrics but does not specify the output structure (e.g., whether results are returned as text, JSON, or a table) or define terms like 'crates' beyond the obvious domain context. For a simple stats tool this is adequate but not comprehensive.

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 the description cannot add parameter-level meaning. The baseline of 4 applies because the schema already confirms no parameters are needed and additionalProperties is false. The description's mention of the exact metrics returned helps compensate for the absence of an output schema.

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

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

The description clearly states the tool provides aggregate statistics: track counts, missing BPM/key counts, crate counts, and database size. It names specific resources and distinguishes itself from siblings like list_tracks or track_detail by focusing on summary metrics rather than individual records. Though it lacks an explicit verb like 'get' or 'show', the meaning is 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 no guidance on when to use this tool versus alternatives such as analyze_missing or list_tracks. There is no mention of prerequisites, contexts, or exclusions. An agent would have to infer usage from the name and brief description alone.

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 lists the fields returned but does not state that this is a read-only operation, how it handles missing IDs, whether there are permission requirements, or any performance implications. For a fetch tool, the safety profile is implicitly read-only, but the description adds no explicit behavioral context beyond the field 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 a single, concise sentence that front-loads the core purpose and lists the key fields. Every word earns its place; there is no fluff or repetition. This is an exemplar of efficient 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?

For a single-parameter fetch tool, the description covers the return content well by listing the fields. However, it does not specify return format nuances (e.g., whether peaks are arrays, how crates are represented), error handling, or pagination. With no output schema and no annotations, an agent might still successfully call it, but there are minor gaps that prevent a higher score.

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%, and the description does not elaborate on the 'id' parameter beyond what the schema already states (an integer). The parameter name is self-explanatory, but the description adds no value about the expected format, range, or how to obtain a valid ID. It fails to compensate for the low schema coverage, though the simplicity of the single parameter prevents a score of 1.

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 a full row for one track and enumerates the specific data fields (tags, BPM/key/camelot, energy, peaks, crates). This is a specific verb+resource. It differentiates from siblings implicitly by emphasizing 'full row' versus list operations, but it doesn't name an alternative, so it's not 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 use this tool versus alternatives like list_tracks or stats. An agent is left to infer that this is for fetching detailed information about a single track. No exclusions or conditions are provided, so the usage context is under-specified.

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