create_literature_note

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

With no annotations, the description carries the behavioral burden and does disclose meaningful traits: creation is template-based, notes go to Zettel/Literature/, and the note tracks multi-pass reading progress. It doesn't cover edge-behaviors like overwriting or permission requirements, but for a straightforward creation action it is reasonably transparent.

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 well-structured: a one-line purpose, a short context block, then a clean Args list and a Returns line. It is appropriately sized for a 7-parameter tool whose schema has no descriptions. Only the final 'Result of the creation' line is somewhat non-specific, but it doesn't hurt usability.

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 creation tool with no annotations, it covers the core context: what is created, where it is stored, what workflow it supports, and what each argument means. An output schema exists, so detailed return handling isn't required. It lacks only explicit sibling differentiation and exact source_type constraints, but an agent has enough to call it 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 0%, so the description fully compensates by explaining every parameter in plain language, including comma-separated authors, the filename-slug purpose of short_title, source_type examples, and extra_vars as additional template variables. This adds real semantic value beyond the bare JSON 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 opens with a specific verb and resource: 'Create a new literature note from the template.' It further distinguishes itself from sibling create tools by specifying the storage location (Zettel/Literature/) and the multi-pass reading workflow, making it clearly different from create_zettel or create_daily_note.

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 clear context for when the tool is appropriate: literature notes are for tracking reading progress through skimming, reading, and completed states. It doesn't explicitly name alternatives or when-not-to-use conditions, but the purpose and storage location are specific enough for an agent to infer the intended use case.

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