tigergraph__drop_query

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

With no annotations provided, the description carries the full burden and does excellently: it explicitly warns that the delete is permanent, cannot be undone, will cause failures for any code calling the query, and cannot be done if the query is in use by other queries. This provides a complete picture of the destructive side effects.

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 with clear sections: summary, Use When, Quick Start, Warning, Tips, and Related Tools. It is concise with no redundant content, and the most important information (destructive nature) is front-loaded in the first sentence and Warning section.

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 description covers the purpose, appropriate use cases, destructive warnings, preconditions, and related tools. It does not mention the success response or error messages beyond the in-use constraint, but since there is no output schema and the operation is a simple delete, these omissions are minor. Overall, it is complete enough for an agent to use the tool safely.

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 input schema already covers 100% of parameters with descriptive text (e.g., profile explains how to select a connection, graph_name default behavior, query_name purpose). The description adds a quick-start JSON example but no additional semantic meaning beyond the schema, so the baseline score of 3 is appropriate.

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 action ('Drop (delete) an installed query from TigerGraph') with a specific verb and resource. The 'Use When' section provides distinct scenarios (removing unneeded queries, cleaning up test queries, before re-installing) that differentiate it from related query tools like install_query and show_query.

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 'Use When' section gives concrete situations for using the tool, and the 'Tips' section advises checking with 'show_query' first. However, it does not explicitly contrast with alternative tools (e.g., 'use show_query instead when you only need to view'), though the scenarios imply the distinctions. This is strong guidance but not maximal.

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