find_cited_questions

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description reinforces them with 'Read-only: no side effects, safe to retry.' It adds meaningful behavioral context beyond annotations: quota cost (10 units/call with free tier context), empty-list semantics ('not that no answer anywhere does'), and the fact that it reads a tracked corpus rather than live answers. This is exactly the kind of extra context an agent needs.

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 long but tightly organized: purpose, usage route, side effects/cost, return shape, caveats, and args. Every sentence earns its place—even the quota warning is decision-relevant for an agent. Key differentiators are front-loaded in the first sentence, and the Args section is cleanly formatted.

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 5 parameters, no output schema, and several siblings, the description is remarkably complete. It covers input constraints, return value shape including nested fields, special empty-list semantics, quota impact, platform/country/language limitations, and how it relates to sibling tools. An agent has everything needed to select and invoke the tool 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?

Schema description coverage is 0%, so the description carries the full burden, and it fully delivers. Each parameter gets practical guidance: domain format ('bare domain, e.g. "example.com" (no https://, no www). Subdomains are included'), platform options and constraints, limit range and default, country semantics including the chat_gpt limitation to United States, and language with the note that 'en' is the only option for chat_gpt. This goes beyond the schema's raw type/default data.

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 a specific verb-object pair: 'Find the questions people ask AI answer engines where a domain is already cited as a source, most-asked first.' It further clarifies the tool starts from the domain rather than keywords, which distinguishes it from sibling tools like check_prompt_coverage and analyze_citation_gap. The stated use case, 'what does ChatGPT already cite us for', makes the purpose immediately identifiable.

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 explicitly says when to use this tool ('Use this to answer...' and 'to pick the keywords to feed check_prompt_coverage and analyze_citation_gap'). It also contrasts behavior with siblings: 'This reads the provider's tracked answer corpus, the same measurement as find_citation_leaders, not a live answer: re-check a question with check_prompt_coverage to see today's answer.' This gives clear routing guidance between alternatives.

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