xql_library_insert

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

With no annotations, the description carries the burden of behavioral disclosure. It discloses the permission requirement and warns about unique query names, but does not explain the behavior when xql_queries_override is false or whether the operation returns a specific response. The override behavior is only spelled out in the schema, not the description.

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 well-structured and front-loaded: a clear summary, then a usage note, permission requirement, endpoint reference, and an illustrative example. Every section adds value, and the example is concise despite being detailed.

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 no output schema and no annotations, the description could be more complete. It covers the core functionality, permissions, and an example, but omits any mention of return values, error handling (e.g., when override is false and a query exists), or pagination/conflicts. The duplicate xql_query_name in the example may also confuse agents trying to infer uniqueness.

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?

The schema has low description coverage (0%), but the description includes a complete example request body that clarifies the structure of request_data and its nested fields (xql_query, xql_query_name, xql_query_tags, xql_queries_override). This adds practical meaning beyond the bare schema, helping the agent construct a valid request.

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 opens with 'Insert or update XQL queries', clearly stating the action (insert/update) and resource (XQL queries). This distinguishes it from sibling tools like xql_library_get and xql_library_delete, leaving no ambiguity about its purpose.

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 clear context for when to use this tool: to insert new or update existing XQL queries. It also includes a practical prerequisite (Instance Administrator permissions) and a uniqueness note, though it doesn't explicitly reference alternatives or exclusion cases.

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