Update a query / API

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

No annotations are provided, so the description carries the full behavioral transparency burden. It discloses that it merges (partial update, only passed fields change, datasource preserved) and explicitly warns that renaming is not supported because it rewrites bindings. This is genuinely useful behavioral context beyond the schema. It doesn't mention idempotency, error behavior, or response format, but the merge semantics and rename limitation are strongly transparent.

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 sentences, zero wasted words. Each sentence earns its place: first establishes the purpose and merge semantics, second clarifies the rename limitation. Front-loaded with the core action and scoping. Excellent economy.

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?

For a 6-param update tool with 100% schema coverage and no output schema, the description covers the essential semantics: merge behavior, rename limitation, and scope. The REST-only restrictions are handled by the schema. Could briefly mention idempotency/response, but for a partial-update tool with strong schema support this is reasonably complete.

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%, so all 6 params are documented in the schema. The description adds meaningful value by clarifying the merge behavior ('Only the fields you pass are changed — the server merges the rest'), which changes how an agent should treat partial updates. The REST-only restrictions are already in the schema. Slight gap: no elaboration on how REST-only vs query params interact with the merge semantics, but overall adds value.

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?

Clear verb+resource ('Edits an existing query or API action') with an explicit merge semantics statement telling the agent that only passed fields change and the datasource/settings are preserved. It also proactively distinguishes from renaming behavior, which clarifies the tool's exact scope against update tools in the sibling list.

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?

States clearly what the tool does (edits existing query/API) and explicitly notes what it does NOT do (rename, which needs a refactor). This contextualizes when the tool is appropriate. However it doesn't name sibling alternatives (e.g., create_query, appsmith_execute_query) explicitly, though the distinction is reasonably implied.

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