hypertune

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

Beyond the readOnlyHint annotation, the description reveals meaningful behavior: it builds a GraphQL query, enforces that every field must supply all arguments, and explains that Hypertune reduces flag logic to a JSON result. It also notes the prerequisite discovery flow, adding non-obvious context. No contradiction with annotations exists.

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 four sentences, front-loads the core purpose, and every sentence carries useful information: what it does, how it builds the query, how to provide inputs, and what to do before calling. There is no filler or redundant restating of the title.

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 two-parameter tool, the description covers purpose, syntax, example selections, context semantics, and prerequisite tool usage. There is no output schema, but the description's mention of a JSON result gives some expectation of return shape. It does not explicitly disambiguate from hypertune_query or describe error cases, so a small gap remains.

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%, and the schema already provides examples for selection and context. The description adds value by framing context as environment plus user/attributes and by noting that every selected field must supply all arguments, which is a critical constraint not present in the schema.

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 and resource: it evaluates feature flags for a given context and returns resolved values, with a concrete GraphQL query template. It is not a tautology and likely stands apart from list/introspect tools, but it does not explicitly differentiate itself from the sibling hypertune_query, so sibling distinction is incomplete.

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 gives explicit pre-usage guidance: use hypertune_list_flags or hypertune_introspect first if flag names are unknown. It also implies this tool is for resolved values versus raw logic, but it does not explicitly state when to prefer this over hypertune_get_logic or hypertune_query.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral detail beyond the schema: it does not reduce flags, it returns configuration logic, and it may accept a partial context when the schema demands one. No contradiction with annotations.

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?

Three sentences with no filler. The core behavior is front-loaded, followed by a concrete query example and a practical edge-case note about partial contexts. Every sentence earns its place.

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 read-only GraphQL query tool with no output schema, the description explains what is returned conceptually (conditional expression / rules), the query shape, and context handling. It does not detail exact response formatting, but that is less critical given the GraphQL nature and no output schema.

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 baseline is 3. The description adds meaning by placing both parameters in the GraphQL query shape, clarifying that 'selection' is the flag field under root and that 'context' is an optional partial inlined when required. This goes beyond the schema's own descriptions.

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 states a specific verb and resource: 'Fetch the underlying LOGIC of flags without reducing them.' It explicitly contrasts with a single resolved value, which distinguishes it from evaluate-like tools even without naming them. The GraphQL query shape is provided, making the tool's function unambiguous.

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 gives clear context: use this to inspect how a flag is configured, especially when you want conditional rules rather than a resolved value. It does not explicitly name sibling tools or state when not to use them, but the contrast with resolved values and the focus on logic provides adequate guidance.

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

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

Annotations already indicate readOnlyHint=true, and the description adds concrete behavioral details: it is best-effort and may return a clear error on deployments with introspection disabled. This goes beyond the annotation by setting expectations for failure modes.

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, with the primary purpose front-loaded and the fallback condition stated in the second. Every clause earns its place; no redundant restatement of the title or annotations.

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 parameterless, read-only introspection tool, the description covers what the query returns (schema types, fields, flags, evaluation context) and the one notable failure mode. A standard GraphQL introspection response format is widely known, so omitting a detailed return schema is acceptable.

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 tool has zero parameters and the schema coverage is effectively 100%, so there is no parameter meaning for the description to add. The 0-param baseline of 4 applies, and the description's focus on output scope 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?

States a specific verb ('introspect'), resource ('GraphQL schema'), and scope ('all types and fields, including the available flags and the shape of the evaluation context'). This clearly differentiates it from sibling tools like hypertune_query or hypertune_list_flags.

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?

Explicitly notes when the tool may fail (disabled introspection) and directs the agent to hypertune_query with a known flag name as the alternative. This gives a when-not and a named sibling, satisfying the highest bar for usage guidance.

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

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

The readOnlyHint annotation already covers safety, and the description adds useful behavioral context by explaining that results come from GraphQL introspection and that introspection must be enabled on the edge endpoint. This is meaningful operational information beyond the annotation. No contradiction exists.

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 three concise sentences with no filler. The main action and result are front-loaded, followed by workflow context and a prerequisite. Every sentence earns its place, and the overall structure is 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?

Given the simplicity of the tool and the absence of parameters, the description covers the essential points: what is listed, how it is derived, when to use it, and what must be enabled. It does not explicitly contrast the tool with the sibling 'hypertune_introspect', but the 'top-level flags' scope and 'before evaluating' framing provide enough context for an agent to call it correctly.

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?

With zero parameters, the parameter-semantics burden is minimal, and the baseline is 4. The description effectively explains what the tool returns, which is sufficient for a parameterless call. There are no parameter semantics to clarify beyond that.

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 that the tool lists the project's top-level feature flags, specifically the fields of the query root type, along with their return types and descriptions. It also identifies the data source as GraphQL introspection, which gives a precise scope and distinguishes the tool from evaluation-focused siblings.

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 phrase 'A convenient first call to see what flags exist before evaluating' gives explicit guidance on when to use the tool in a workflow. It also mentions the introspection prerequisite. It does not name alternative tools or conditions when not to use it, so it is strong but not fully explicit about exclusions.

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

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

readOnlyHint=true already establishes safety, and the description adds meaningful context: each Hypertune project has its own generated schema, and the query root field is root(context: ...). It does not describe error behavior or response shape, but the annotation covers the safety profile.

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?

Three sentences with no filler: the core action is front-loaded, the second sentence justifies its role as an escape hatch, and the third provides the essential root-field detail. Every sentence earns its place.

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 deliberately unconstrained raw GraphQL tool, the description explains why no fixed output shape is possible and gives the key entry-point detail. It could mention the raw response/error behavior more explicitly, but given the project-specific schema and readOnly annotation, the coverage is solid.

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 100%, so the parameters are already well documented. The description adds minor color about nested selections and enum literals but does not materially change how an agent should fill in query or variables beyond the schema.

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?

States a concrete action ('Run an arbitrary GraphQL query') and a clear resource ('Hypertune edge endpoint'), then labels itself a 'power-user escape hatch'. This makes its purpose distinct from the convenience sibling tools without needing to open their schemas.

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?

Explicitly frames when to use this tool: for anything the convenience tools cannot express, such as nested selections, inline enum literals, or unusual variables. It does not name the specific sibling alternatives, but the exclusion logic is clear.

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