update_search_query

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

With no annotations, the description carries the behavioral disclosure burden. It discloses the critical non-obvious behavior that the SQL query is immutable after creation, which prevents users from expecting to modify it. It does not mention other behavioral aspects like permissions or return values, but for a simple update tool, this is a meaningful and sufficient disclosure.

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 two sentences with no redundant wording. The action is front-loaded, and the critical note about SQL immutability is placed at the end. Every word earns its place, making it highly concise and well-structured.

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 simple update tool with three parameters and no output schema, the description is adequate but leaves gaps: it does not clarify whether updates are partial or full, whether both name and description can be updated in one call, or what happens if an attempt is made to change the SQL query. These are relevant for successful invocation and correct behavior, so the description is not fully 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 description coverage is only 33% (only id has a generic description). The description adds minimal value by stating that name and description are updatable, but it does not clarify the id parameter's meaning (e.g., that it references the search query ID) or provide any format or usage details. With low schema coverage, the description should compensate more thoroughly.

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 updates a saved search query's name or description, using a specific verb and resource. It distinguishes itself from sibling tools like create_search_query, delete_search_query, and get_search_query by explicitly limiting updates to name/description and noting that SQL cannot be changed.

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 when to use this tool (to update name/description) and provides a key constraint: the SQL query cannot be changed after creation, effectively telling users not to use this tool for SQL changes. However, it does not explicitly name alternative tools or provide a when-not-to-use scenario beyond the SQL limitation.

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