sage_task

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

With no annotations, the description carries full behavioral burden. It discloses that tasks persist without decay until completed/dropped, which is key behavioral context. However, it does not mention return values, error handling, authentication requirements, or side effects beyond persistence. The transparency is adequate but not complete.

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: it starts with the core purpose, then defines behavioral characteristics, then lists usage patterns. It is front-loaded with the most important information. While slightly verbose (multiple paragraphs), it remains clear and each sentence adds value. Could be trimmed, but overall good.

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 tool with 5 parameters and no output schema or annotations, the description is fairly complete. It covers all three intended operations, explains persistence behavior, and gives examples of appropriate use cases. However, it lacks information about return values, error conditions, or constraints like rate limits. This is a minor gap given the tool's complexity.

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% with descriptions for all 5 parameters. The description adds value by grouping parameters into three usage patterns (create, update status, link related memories), clarifying how parameters combine. It also specifies the domain default and explains the purpose of each parameter in context, going beyond the schema's isolated descriptions.

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 clearly states 'Create or update a task in your persistent backlog' and explains tasks persist until completed/dropped. It distinguishes from sibling tools like sage_backlog (which likely lists backlog) and sage_forget (which deletes) by focusing on the task lifecycle and persistence semantics.

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 description provides explicit usage patterns: 'To create: provide content + domain', 'To update status: provide memory_id + status', 'To link: provide memory_id + link_to'. It also states when to use: 'to track planned work, feature ideas, bug reports, and anything that should survive across sessions'. However, it does not explicitly mention when to use alternatives, only implies via patterns.

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