save_project_document

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

With no annotations provided, the description fully carries the behavioral burden, and it delivers: declares itself a mutating tool, specifies storage side effects (writes to local vault, updates manifest), states what it does NOT do (no AI provider calls, no overwriting), and documents preconditions (existing project, valid kind, user approval, write permission). This is exemplary disclosure for an unannotated 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?

Each of its six sentences carries unique weight: purpose, mutation warning, storage side effects, non-AI assurance, idempotency guarantee, validation rules, approval precondition, and permission model. Zero filler words, logic gate final section is a nice touch. Perfectly proportioned for the tool's complexity.

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 mutating tool with 4 parameters, 0% schema coverage, and no annotations, the description covers the full range: side effects, constraints, preconditions, permission requirements, and validation rules. The presence of an output schema means return-value documentation isn't needed. Nothing missing for an agent to safely invoke this tool.

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 must compensate — and it does meaningfully. It documents that `project_id` must reference an existing project and that `kind` accepts only four values (`knowledge`, `task`, `decision`, `handoff`), none of which are in the schema itself. The remaining params (title, body) are self-evident from the schema names, so minimal description is 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 opens with a specific verb+resource+scoping: 'Create a new durable document inside one EleSync project.' It clearly distinguishes itself from siblings by noting it 'writes to local vault storage' and 'does not send content to an AI provider,' which differentiates it from recall/remember tools. The distinction is crisp and actionable.

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?

Provides explicit when-to-use guidance: 'Call it only after the user has approved saving the content,' plus permission constraints for project-bound connections. While it doesn't name sibling alternatives explicitly like 'use recall_project instead,' the alternatives guidance is implied by context. The exclusion of AI-provider sending and the statement that each call creates a new document clarify when NOT to worry about overwrites.

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