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

The description goes beyond annotations (which are all false) to disclose critical behaviors: the tool validates the entire definition before saving, rejects invalid inputs, sanitizes names, enforces uniqueness, and grants permanent ownership. It also warns that args_template is parsed but not evaluated, and explains the implications of using connections (delegation). These are important facts that an agent needs to know to avoid errors.

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 each sentence earns its place. It is organized logically, starting with the core action, then validation rules, naming, ownership, and usage context. Though long, it is front-loaded with the most critical information (what the tool does) and avoids fluff. A slightly tighter structure could improve readability, but overall it's effective.

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?

Given the tool's high complexity (multiple steps, connections, JSONata, validation rules) and that there is no output schema, the description covers all essential aspects: what it creates, how steps are defined, validation rules, naming, ownership, and follow-up steps. There are no critical gaps that would leave an agent guessing.

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%, and the schema already describes each parameter in detail. The description adds value by explaining how the parameters interact (e.g., steps' args_template reads from input and steps, depends_on orders the DAG) and providing context on the input_schema's relationship to execution. This supplementary context enhances the schema's clarity.

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: authoring a new multi-step synthetic tool with a named input_schema and a DAG of steps. It uses specific verbs ('Author a new multi-step Elaichi tool') and identifies the key resources (input_schema, steps, connections, tools). It is distinct from siblings like update (which modifies existing tools) and execute (which runs them), so an agent can easily tell them apart.

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 guidance on when to use this tool (to create a new synthetic tool) and implies when not to (use update for existing tools). It also instructs agents to pin the created tool into a toolbox to make it runnable, and mentions using connection.list_tools for tool names. This helps the agent select the correct sibling and follow the right workflow.

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