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

With no annotations, the description carries the full behavioral burden. It discloses formatting/serialization to .evox and validation of the AST, but omits duplicate/existing-song handling, permission requirements, and whether creation is destructive or reversible.

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 tight sentences with the core action and output format front-loaded. There is no wasted wording or tangential detail.

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 complex, with nested columns/stanzas/lines, five parameters, no output schema, and no annotations. The description covers the core create-and-serialize behavior, but is thin on operational context such as upsert/overwrite and target directory; the rich schema supplies parameter detail, so 3 is appropriate rather than lower.

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 and nested fields are already documented in the schema. The description only alludes to the structured AST and adds no syntax or format detail beyond what the schema provides, making baseline 3 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 uses a specific verb, "Creates," and resource, "a new song," and adds the source (validated structured AST) and output format (.evox markup). It does not explicitly name update_song or other siblings, so it stops short of full sibling differentiation.

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 when-to-use guidance, prerequisites, or alternatives are given. The reader must infer that this is the creation path and that update_song handles existing songs; upsert behavior is documented only in the schema.

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 for a destructive operation. It does not state whether deletion is permanent or reversible, whether confirmation is required, what happens if the slug does not exist, or whether the file is moved to a trash location.

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 short sentence that front-loads the action and resource with zero filler. Every element (verb, resource, file type, location) 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 destructive mutation with no annotations and no output schema, the description is too thin: it omits irreversibility, failure behavior, and any confirmation expectations. The parameter surface is small and well documented, but the risk profile of the operation is not communicated at all.

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 both the required slug and the optional project_dir are already documented in the schema. The description's mention of the songs/ folder gives minor context about where the file lives but adds no syntax, format, or validation 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?

The description states a specific verb and resource ("Deletes a song") and adds the file type (.evox) and location (songs/ folder), so an agent knows exactly what is removed. It does not explicitly contrast itself with siblings such as update_song or create_song, but the destructive verb makes the distinction obvious.

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 update_song or any other sibling, nor any stated preconditions such as confirming the song exists first. The only implied usage is the tool's name itself, leaving the agent to infer the 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, the description carries the full burden and does substantial work: it discloses a destructive side effect (deleting stray OS files from songs/), a validation gate on all song syntax, the write target (book/book.pdf), and the shape of the return (PDF details plus an alphabetical Table of Contents). What's missing is failure behavior – whether invalid syntax aborts generation or what happens to a pre-existing book.pdf.

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 packed sentences with zero filler; the output artifact and command are front-loaded, and each subsequent clause adds a new behavior (cleanup, validation, return contents) rather than restating anything.

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 2-parameter, no-required-args tool with no output schema, the description covers what it produces, where it writes, what it mutates, and what it returns. The only meaningful gap is error/failure semantics, which an agent would want before invoking a tool that deletes files and validates the whole corpus.

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 both parameters (skip_cover, project_dir) are fully documented in the schema, including defaults and the EVOX_PROJECT_DIR fallback. The description adds no parameter-level meaning of its own, 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 and resource ('Compiles the songbook into book/book.pdf') plus the underlying mechanism ('evox generate'), which clearly separates it from read-oriented siblings like get_songbook or get_song. It stops short of naming a sibling or explicitly contrasting with get_songbook, so it is clear but not maximally differentiated.

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

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

Usage is only implied: the cleaning and syntax validation steps suggest this is the build/finalization tool to run after songs exist, but there is no explicit 'use this when' statement and no prerequisites (e.g., songs must already exist, evox CLI must be installed) are given. No alternatives or when-not-to-use conditions are named.

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 supplied, the description carries the full burden, and 'Reads' does signal a non-destructive operation plus it discloses the returned content shape. However, it says nothing about behavior when cover/config.yml or the logo file is absent, whether defaults are returned, or how 'file status' is represented, which are the likely points of confusion for this tool.

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 the resource front-loaded and the returned fields grouped in a parenthetical. Nothing is redundant, though the trailing 'logo image file status' clause is slightly vague for the space it occupies.

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

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

For a simple single-parameter read tool with no output schema, the description adequately conveys what is read and roughly what comes back. The remaining gap is behavior on missing config or logo files, which matters given there are no annotations to fall back on.

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% for the single optional 'project_dir' parameter, including its fallback to EVOX_PROJECT_DIR or cwd, so the baseline is 3. The description adds no additional meaning about path resolution or scoping beyond what the schema already states.

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 concrete verb and resource ('Reads cover/config.yml') and enumerates the content returned (header, logo dimensions, footer, logo image file status), so an agent can tell it apart from the mutating sibling update_cover. It stops short of explicitly contrasting itself with get_songbook, which reads the broader songbook config, so sibling differentiation is implicit rather than stated.

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 when-to-use or when-not-to-use guidance, and no named alternatives. The read-only nature implies it should be called before inspecting or modifying cover settings, but the agent is left to infer that update_cover is the counterpart and that get_songbook covers a different scope.

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. It does well on the return shape, spelling out that the result includes title, artist, font, column width, gutter, and chord-lyric pairs, but it says nothing about read-only semantics, failure behavior for an unknown slug, or how project_dir resolution affects the lookup (that detail lives only in 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?

A single front-loaded sentence with the verb and key identifier first, followed by the parenthetical payload list. Every clause earns its place because the payload detail substitutes for a missing output 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?

For a simple two-parameter read with no output schema, the description supplies the most important missing piece: what the returned AST contains. The remaining gap is error/not-found behavior and explicit read-only framing, which are minor for this complexity level.

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 both slug and project_dir are already documented in the schema, and the description only echoes the slug-based lookup. Baseline 3 applies since the description adds no syntax, format, or fallback meaning beyond the structured fields.

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 ("Retrieves") and resource ("full structured AST for a song by slug") and enumerates the returned components, so the agent knows this is a single-song fetch rather than a listing. It does not explicitly name the sibling it differs from (e.g., list_songs or get_songbook), which keeps it just 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?

Usage is implied by "by slug" — use this when you already know the song identifier — but there is no explicit when-to-use/when-not guidance and no pointer to alternatives like list_songs for discovery. An agent must infer the selection criteria from the sibling names 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?

No annotations are provided, so the description carries the full burden. It discloses the returned status components and "Returns" implies a read-only operation, but it does not explicitly state whether files are modified, what permissions are needed, or how warnings are represented.

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 lists the relevant status components without filler. Each listed item contributes to understanding what the tool reports.

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

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

With no output schema, the description usefully enumerates what the status response includes. The sole optional parameter is fully documented in the schema, though the description does not add safety or alternative-use 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 100%, and the schema documents project_dir and its default behavior. The description adds no parameter-level meaning beyond what the schema already provides, so the baseline of 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: "Returns comprehensive status of the songbook," then enumerates the status areas. This clearly distinguishes it from sibling tools like list_songs, get_song, get_cover, and generate_songbook by framing it as an aggregate diagnostic view.

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 as checking songbook status, but the description does not explicitly say when to use this tool versus get_cover, list_songs, or other siblings, nor does it state any exclusions.

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 supplied, the description carries the full behavioral burden. It discloses which directories are created, but says nothing about what happens if project_dir already exists, whether files are overwritten, whether a config file is written, or what the tool returns on success or failure.

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 no filler that names the action, the created structure, and the underlying command. It is efficient, though the space saved could have been used for one clause on prerequisites or overwrite behavior.

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-required-parameter scaffolding tool with a nested options object and no output schema, the description covers what is created but omits the outcome (return value or confirmation), existing-directory handling, and its role as a prerequisite for the sibling tools. Adequate but with 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 100% and the nested cover object is fully documented with defaults in the schema, so the baseline is 3. The description adds no meaning about project_dir resolution, the effect of include_sample_songs, or how cover customizations map to generated files beyond what the schema already states.

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 gives a specific verb and resource ("Initializes a new Evox songbook project") and enumerates the concrete artifacts (book/, cover/, songs/) plus the underlying command 'evox init'. It does not explicitly contrast itself with siblings such as generate_songbook or get_songbook, so an agent must infer that this is the scaffolding step rather than the build step.

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 word "Initializes" and "new ... project" imply first-time setup, but the description never states when to call this versus generate_songbook, nor that it should be run before create_song or list_songs. No exclusions or prerequisites are given, leaving usage to inference.

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 supplied, the description carries the full behavioral burden. It does add real value by disclosing the sort order and that it matches the compiled PDF and Table of Contents, but it never states read-only behavior, what each returned song contains, or what happens when the directory is missing or empty.

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 sentence, front-loaded with the verb and resource, with the ordering detail placed immediately after. Nothing is padded or 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?

For a simple read-only list tool this is close to sufficient, but with no output schema the description should indicate the shape of each returned song (titles only vs. full records), since the agent cannot learn that anywhere else.

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

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

Schema coverage is 100% and the single optional project_dir parameter is fully documented in the schema, including its EVOX_PROJECT_DIR/cwd fallback. The description adds no parameter meaning beyond that, so the 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 gives a specific verb and resource ('Lists all songs in the songbook') plus the ordering contract, so it is clearly distinct from get_song, create_song, or update_song. It stops short of naming any sibling explicitly, which keeps it from 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?

Usage is only implied: an agent can infer this is the bulk-retrieval tool while get_song handles a single song. There is no explicit when-to-use statement, no exclusion, and no mention of prerequisites such as whether the songbook must be initialized first.

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 usefully disclose the mutation target file (cover/config.yml) and the side effect that a local image can be copied into cover/. However, it omits critical mutation semantics: whether omitted fields retain existing values or fall back to the schema defaults, and whether logo_source_path overwrites an existing logo file.

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 dense sentence that front-loads the target file and then enumerates the modifiable areas, ending with the optional image side effect. 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?

For a no-output-schema mutation tool with nested objects, the description covers the modifiable surface and the one non-obvious side effect. Remaining gaps (merge-vs-default behavior, overwrite semantics, post-update regeneration) are real but modest given the fully documented schema.

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% with per-property descriptions for the nested header/footer/logo objects, so the schema does the heavy lifting. The description confirms the field groups and hints at the image-copy behavior of logo_source_path but adds no format, constraint, or interaction details 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 ('Updates') plus the exact resource ('cover/config.yml') and enumerates the settings groups touched (header titles/padding, logo size/image name, footer title/size). The read/write split against the sibling get_cover is self-evident from the names, though the description never names that 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?

Usage is only implied: an agent can infer this is the tool for changing existing cover configuration versus init_songbook for setup. There is no statement of prerequisites (e.g., an existing songbook project, whether generate_songbook must be re-run afterwards) and no 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, the description carries the full behavioral burden for a mutation tool. It says columns can be replaced but never states that supplied columns overwrite the existing structure wholesale (that nuance lives in the schema), nor what happens if the slug is unknown or the new_slug already exists.

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 sentences, front-loaded with the core action followed by the supported modes, with no filler. It is efficiently sized, though the second sentence compresses three distinct operations into a list without elaboration.

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 mutation with nested column objects, no annotations, and no output schema, the description is thin. It omits failure behavior, rename-collision handling, and any indication of what the caller gets back, leaving an agent to guess at 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 description coverage is 100%, so every parameter is already documented in the schema, establishing a baseline of 3. The description adds only a loose mapping of the three change modes to columns/metadata/new_slug, with no syntax or interaction details beyond that.

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 ("Updates an existing song") and enumerates the three supported change modes: metadata, columns, and slug rename. This distinguishes it from create_song and delete_song by implication, 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?

"Existing song" implies create_song is the tool for new songs, and "partial" clarifies that full replacement isn't required. However, there is no explicit when-to-use/when-not guidance and no mention of preconditions such as the slug needing to already exist.

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