create_bookAdd a new BookStack book with a name, tags, and description, and optionally assign it to a shelf.
Create a book, optionally placing it on a shelf.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| tags | No | Tags as {name, value}. When updating, this replaces all existing tags. | |
| shelf_id | No | Also add the new book to this shelf | |
| description | No | Short plain-text description |
Changes observed during successful MCP inspections.
v0.1.0Does 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 says nothing about permissions required, whether the book is immediately visible/searchable, or that supplying tags replaces existing tags (that fact lives only in the schema). The one behavioral clue is that shelf placement is optional.
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 with zero padding and the primary action front-loaded. It is efficient, though the brevity edges toward under-specification for a four-parameter mutation 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?
For a mutation tool with no annotations and no output schema, the description is too thin: it omits required fields, the tags replacement behavior, and any note on what is returned. An agent can call it, but only by leaning almost entirely on the 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 75%, so the schema already documents shelf_id, tags, and description reasonably well. The description's only parameter-relevant addition is "optionally placing it on a shelf," which merely restates the shelf_id schema note rather than adding format or constraint detail.
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 ("Create a book") and adds a scope note about optional shelf placement. It does not distinguish itself from sibling creation tools like create_chapter, create_page, or create_shelf, so an agent gets no routing help, but the core action 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 phrase "optionally placing it on a shelf" hints that shelf_id is optional, but there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives among the many sibling creation tools. The agent must infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.