add_notify_state

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

Beyond the obvious write operation, the description provides no behavioral details (e.g., whether existing notify states are replaced, whether the track must exist, any side effects). Does not complement any annotations since none are provided.

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 brief with a single sentence introducing the action, followed by a structured list of parameters. The Arg list is somewhat redundant with the schema's properties but necessary here due to zero schema descriptions. The overall structure is easy to scan.

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?

The tool has 5 required parameters and an output schema, but the description omits important context: when to use it, whether it modifies the asset destructively, what the output contains, and typical usage scenarios. With no annotations, the description is insufficiently complete for an AI agent to invoke it confidently in diverse situations.

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?

The description includes an Args block that gives a sentence for each of the 5 parameters, providing minimal semantics (e.g., 'time' is 'Start time in seconds'). While schema itself has zero descriptions, this coverage helps somewhat, though it remains shallow and lacks details like path formatting or class naming conventions.

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 clear action: adding a notify state to an animation. Distinguishes from sibling tools like add_notify and add_notify_track, which add points or tracks, respectively. The verb-resource pairing is specific and 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?

No guidance on when this tool should be used instead of alternatives such as add_notify or set_notify_time. Lacks exclusions, prerequisites, or typical scenarios.

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