automation_add_curve

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

With no annotations provided, the description carries the full burden. It transparently discloses the reuse behavior: 'Reuses an existing curve ... rather than creating a duplicate,' implying it creates a new curve if none exists. It also explains how driver_type alters the interpretation of points (parameter value vs. seconds). However, it does not mention side effects, error conditions, or return values, which are minor gaps for a mutation 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?

The description is efficient and well-structured. It leads with the core purpose and a concrete example, then a key behavioral note, then a bulleted Args section that covers all five parameters. Each sentence adds necessary information with no fluff, and the 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 is moderately complex with 5 parameters and no output schema, and the description covers parameter semantics, the reuse behavior, and the driver-type nuance, which is substantial. However, it does not mention what the tool returns (e.g., success indicator or curve ID) or any prerequisites like whether the referenced driver must already exist. These gaps are not blocking for invocation but leave some uncertainty, so a 4 is warranted.

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 is the only source of parameter meaning. It thoroughly explains each param: target specifies valid GUID types and warns against using trackGuid, property lists allowed values, driver distinguishes parameter vs event forms, driver_type clarifies the two modes, and points explains the structure and position semantics depending on driver_type. This exceeds schema-level documentation significantly.

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?

Description opens with a specific verb-resource pairing: 'Bind a property to a curve so it changes as the driver changes', immediately clarifying what the tool does. It further distinguishes itself from automation_list by noting the reuse behavior and advising to call automation_list first if unsure about an existing curve, so an agent can differentiate sibling tools without opening schemas.

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 gives one explicit usage heuristic: 'call automation_list first if unsure whether one's already there,' which is helpful for avoiding duplicates. However, it does not contrast this tool against automation_add or other automation-related siblings, nor does it state when this tool is preferred over alternatives. The guidance is present but minimal, so a 3 is appropriate.

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