Save chunks to a JSONL file

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the description's job is to scope the damage, which it does: it writes only the one .jsonl file and replaces it if present, and it never modifies the input Markdown. That clarifies exactly what the destructive hint applies to. It stops short of mentioning any failure modes (e.g., invalid output_path extension, unreadable input), which keeps it from a 5.

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

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

Four short blocks, front-loaded with the core action, then destination guidance, then the write-scope caveats, then the return shape. No sentence repeats the name or the schema, and each one carries distinct 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?

There is no output schema, and the description compensates by naming the returned keys (output_path, chunks, bytes, biggest_chunk_chars). Combined with full parameter documentation, explicit overwrite behavior, and sibling routing, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, with defaults, bounds, and semantics (max_chars in characters not tokens, overlap limited to half of max_chars) all documented in the schema. The description adds only the relationship "the chunks are the same as chunk_markdown gives" and does not elaborate on output_path or prefix_path beyond what the schema states, 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 opens with a specific verb and resource: "Split a Markdown file into chunks and save them as a JSONL file (one chunk per line)." It explicitly positions itself against the sibling chunk_markdown, noting the chunks are the same but the destination differs, so an agent can distinguish the two without reading either schema.

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

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

It gives a concrete when-to-use condition (chunks feeding a search index, vector database, or another program where a file is preferable to a long chat reply) and an explicit exclusion with the alternative named: "Do not use it to look at chunks in the chat (use chunk_markdown)." Both the positive and negative routing cases are covered.

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