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

Annotations already declare a read-only, closed-world, non-destructive tool, and the description adds real substance beyond them: unverified 2-K records are dropped from positive 2-K filters, results cap at 20 per page with match reasons, source years and profile links, and missing scores are not zero. The main omission is whether pagination via offset is stable or what the total-count behavior is.

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?

Four tight sentences, each carrying distinct information, with scope stated first and caveats (2-K exclusion, missing scores) trailing as clarifiers. Slightly dense with caveats but nothing is redundant or padded.

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 broad 14-parameter search with no output schema, the description covers scope, result shape (count cap, match reasons, source years, profile links), filter semantics for the trickiest fields, and the key negative caveats. Remaining gaps around grade/grade_band interaction and pagination keep it short of 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?

With 14 parameters and only 21% schema coverage, the description must compensate and largely does: it explains that school_type uses a conservative classification that excludes unknown types, that program filters reflect recorded flags, that min_overall_score is a non-official rating with absent values not treated as zero, and that 2-K filters exclude unverified records. It still does not disambiguate grade vs grade_band or district vs borough, or state defaults for limit/offset, keeping it below the top score.

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?

Opens with a specific verb and resource ("Find canonical NYC school records") and enumerates the dimensions it searches over (name/identifier, grade, borough, district, school type, program flags). The closing "This is discovery, not admissions eligibility or a placement recommendation" distinguishes it from evaluation-style siblings, though it never names compare_schools or get_school_details directly.

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?

Frames the tool as discovery and explicitly excludes admissions-eligibility and placement-recommendation use, which usefully narrows expectations. However it gives no positive routing guidance, such as when to follow up with get_school_details or switch to compare_schools, so the agent must infer the handoff.

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