shelly_script_create

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

With only idempotentHint in the annotations, the description carries most of the burden and does add real behavioral context: the call is 'Audit-logged', it returns an 'id', and the subsequent code-attachment step is confirm-gated. It does not mention permissions or what happens on a name collision, but the audit/confirm disclosures are genuinely beyond the structured fields.

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?

Two short sentences, front-loaded with the action and its result, then the essential next step. Nothing is padding; every clause carries information an agent needs.

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 workflow context (create then put code) and the return value are covered, and an output schema exists so return details needn't be expanded. However, for a tool whose schema has 0% description coverage, leaving the required 'device' parameter entirely unaddressed is a meaningful completeness gap.

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, but it only explains one of the two parameters ('optionally named' maps to 'name'). The required 'device' parameter — the one that determines which device the script lands on — is never mentioned, leaving the most important argument undocumented in both the schema and the description.

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 specific verb and resource ('Create an empty script') and clarifies the scope ('optionally named'), which cleanly separates it from siblings like shelly_script_put_code and shelly_script_list. An agent can identify what this produces (an empty script with an id) without opening the schema.

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?

Explicitly routes the agent to the follow-up step: 'Use shelly_script_put_code to give it code', and flags that step as confirm-gated, which is useful planning context. It does not state when *not* to use this tool (e.g., if a script already exists) or any prerequisites for the required 'device' argument.

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