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

Annotations already cover read-only, idempotent and closed-world, and the description adds genuinely new behavior: a hard cap of 10 results, the returned fields (paper_id, title, session, duration, total marks, links), and the meaning of answer_on_screen including which parts can only be answered on exam.now. It says nothing about auth or rate limits, but for a search tool the disclosure is above the bar set by the 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?

The core purpose and the example query come first, followed by return values and the follow-up tools, which is good front-loading. It is a single dense block with an embedded parenthetical about graph/drawing parts that is slightly cumbersome but still 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?

With no output schema, the description correctly spends its space enumerating return fields and the answer_on_screen flag, which is exactly what an agent needs. The remaining hole is input-side: with zero required parameters and nine filters, it should state that parameters are optional and how they combine.

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 only 44%, and the description compensates mainly for query by paraphrasing it with an example, while board, year, series, variant, paper, qualification and subject_code are left to the schema. Critically, it never explains whether query and the structured fields can be combined or how conflicts are resolved, nor that all nine parameters are optional — a real semantic gap for a 9-param tool.

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 gives a specific verb and resource (find Cambridge/AQA/Edexcel past papers on exam.now) and grounds it with concrete query examples like "0580 june 2024 paper 4". It also signals the handoff to get_question, get_mark_scheme and get_paper, so an agent can place it in the workflow without opening any 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?

It clearly frames the two entry modes (free-text query vs structured fields) and states the follow-up path via paper_id, which is real when-to-use guidance. It never contrasts with find_questions_by_topic or states when search is the wrong choice, so the exclusions are missing.

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