tigergraph__get_query_metadata

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

With no annotations provided, the description carries the full burden of conveying behavior. Although it does not explicitly state 'read-only' or 'no side effects', the verb 'Get metadata' strongly implies a non-mutating operation. The mention of 'parameters, return type, and other details' gives a reasonable hint about the output. This is adequate for a metadata retrieval tool.

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', 'Tips', and 'Related Tools'. While it is longer than the minimal two‑sentence example, every section adds useful guidance and there is no redundant or filler content. The layout makes it easy to scan.

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 tool with only three parameters, no output schema, and no nested objects, the description is reasonably complete. It explains what the tool does, when to use it, how to pass parameters (including defaults), and connects to related tools. It does not describe the return format in detail, but for a metadata getter this is acceptable and not a critical 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?

The input schema has 100% description coverage, and each parameter description adds practical context. For example, 'profile' explains 'Omit to use the active default profile' and references 'list_connections', while 'graph_name' notes 'If not provided, uses default connection.' This goes beyond simply naming the parameters and helps the agent decide what to supply.

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: 'Get metadata about an installed query including parameters, return type, and other details.' It uses a specific verb and resource, and the 'Related Tools' section distinguishes it from similar tools like 'show_query' and 'run_installed_query' by clarifying what this tool retrieves versus what others do.

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 explicit 'Use When' scenarios (e.g., 'Understanding query parameters and signature') and a 'Tips' section that advises using 'show_query' for the actual query text, offering guidance for alternative tools. It does not explicitly mention when not to use the tool, but the use cases are sufficiently clear.

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