td_set_params

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

With no annotations, the description carries the full burden of disclosing behavior. It does this well by explaining index checks, local validation with `op_type`, the owner-claim requirement, and that a write can be refused. It does not describe side effects or permissions beyond owner checks, but the output schema covers return value expectations.

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 compact and front-loaded with the core action. Each subsequent sentence adds distinct behavioral or parameter guidance without repetition or fluff. The line breaks make the value-format and usage notes 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 moderate complexity, no annotations, and zero schema descriptions, so the description needs to cover a lot. It handles value formats, owner requirements, and local validation well. But it omits any explanation of what `path` refers to and how parameter names in `pars` map to the operator schema, so an agent may struggle to construct a correct call.

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. It explains value formats for `pars` (constant, expr, bind, pulse) and gives meaning to `op_type` and `owner`. However, the main parameters `path` and the structure of `pars` keys are not explicitly described, leaving a meaningful gap for agents.

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 states a specific verb and resource: 'Set parameters on an existing operator'. It also adds operational context ('checked against the index first'), which clarifies what this tool actually does beyond the name. This is distinct from sibling tools like td_set_flags or td_annotate.

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 useful invocation guidance: pass `op_type` for local validation and pass the correct `owner` to avoid a refused write. However, it does not explain when to choose this tool over an alternative, such as td_set_flags or td_annotate. Usage context is implied rather than explicit.

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