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

With no annotations, the description carries the load and does disclose the key behavioral trait that this is read-only and mutations are refused, plus that it authenticates through Caddie's Linear connection. It says nothing about rate limits, pagination, error behavior, or what shape results come back in — significant for an arbitrary GraphQL passthrough.

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?

One front-loaded sentence with the core purpose first, the scope boundary second, and the example parenthetical last. The inline example is long but earns its space by demonstrating the query format; nothing is redundant.

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 GraphQL passthrough with no output schema and no annotations, the description should say more about response shape and how `variables` binds to the query. It covers the query param and the read-only constraint well, but leaves the caller guessing on variables and return values.

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 0%, so the description must compensate. The embedded `issue(id: "ONC2-123") { title description comments { nodes { body user { name } } } }` example usefully conveys that `query` takes raw GraphQL syntax including nested selections. The `variables` parameter, a nested object, is never mentioned at all, leaving half the inputs undocumented.

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 and resource — 'Run any read-only Linear GraphQL query' — and immediately scopes it against the sibling tools linear_issues and linear_cycles, naming the resource families (projects, comments, labels) those don't cover. An agent can distinguish this from the structured Linear siblings without opening either schema.

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?

Provides a clear routing rule: use this for what linear_issues and linear_cycles don't cover, plus a concrete example (single issue by id). It also states the exclusion 'Mutations are refused.' It doesn't mention the other Linear siblings (linear_comment, linear_update_issue) that could be confused with this escape hatch, so not quite a 5.

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