Manage custom parameters

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

The description provides rich behavioral detail beyond the annotations: it discloses transactional rollback, built-in protection, EXPORT being held with error, and EXPRESSION/BIND requiring specific settings. This significantly enhances the destructiveHint and openWorldHint annotations with concrete safety and failure semantics.

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 dense but efficient, with each sentence adding unique value about transactionality, types, restrictions, and rollback. It is slightly long but the complexity justifies the length. The main purpose is front-loaded, making the tool's role immediately clear.

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 description covers transactionality, restrictions, supported types, and failure behavior comprehensively, which is essential for a complex tool with 5 parameters and no output schema. It does not mention return values, but the operational focus makes this acceptable. Overall, it provides enough context for correct invocation.

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?

With 0% schema description coverage, the description partially compensates by listing supported parameter types and explaining modes like EXPRESSION, BIND, and EXPORT. However, it does not elaborate on comp_path, page, operations, or idempotency_key, relying on their self-explanatory names. This is adequate but not thorough.

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 the tool's purpose: transactionally add, edit, delete, sort, and organize a COMP's custom parameters. This specific verb+resource combination distinguishes it from siblings like edit_td_node_metadata or set_parameters_batch, which focus on other parameter management tasks.

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 implies usage for managing custom parameters but does not explicitly state when to use this tool over alternatives. It mentions 'Legacy page+params calls remain valid' but does not contrast them with this route, and there is no explicit when-not guidance. Some context is given about restricted mode and required settings, but not enough to clearly guide tool selection.

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