thumbtack_graphql

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

Beyond the annotation readOnlyHint=true, the description discloses that the endpoint is anonymous (no auth needed), that introspection is disabled upstream (field names must come from Apollo state), and that mutations are refused. These are non-obvious behavioral details that help the agent avoid failed calls. 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, each earning its place: purpose, a critical caveat about introspection, and a constraint on mutations. The most important information is front-loaded in the first sentence. No redundant filler.

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 essential context for a generic escape-hatch tool: what it does, the read-only restriction, the lack of introspection, and the need for Apollo state. It doesn't describe return format, but for GraphQL the query itself predetermines the response shape, so this is acceptable. Given the absence of an output schema, slightly more detail could be helpful, but it's largely complete.

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 already provides complete descriptions for both parameters (query and variables), with query explicitly stating it must not contain mutation or subscription. The description reinforces this ('mutations refused') but doesn't add new syntax or format details. With 100% schema coverage, the baseline 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 opens with 'Escape hatch: issue an arbitrary read-only query against Thumbtack's anonymous GraphQL endpoint.' This clearly states the action (issue query), the resource (Thumbtack's GraphQL endpoint), and the scope (arbitrary read-only). The 'escape hatch' wording distinguishes it from sibling tools that serve specific lookup purposes.

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 'escape hatch' implies use when specialized tools (e.g., thumbtack_search_pros) are insufficient, and the description adds concrete constraints: 'Introspection is disabled upstream, so field names must come from a page's Apollo state' and 'Mutations are refused.' While it doesn't explicitly list alternatives, the context clearly guides when this tool is appropriate.

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