find_campuses_in_district_boundary

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

The description adds substantial behavioral context beyond the annotations: default boundary_delivery avoids huge payloads by returning a Census TIGERweb download_url, response_profile controls payload size, pagination via cursor/next_cursor prevents truncation, and payload.table/payload.exports provide deterministic output. It also discloses follow-up requirements for incomplete results. Annotations already declare readOnly/idempotent/destructive flags, so the description's extra details are valuable and non-redundant.

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 a single dense paragraph, but every sentence provides useful information for a complex tool (13 parameters, no output schema). It is front-loaded with purpose and usage, then dives into parameter behavior. The length is justified by the tool's complexity, though breaking it into shorter paragraphs or bullet points would improve scannability.

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?

Given 13 parameters, no output schema, and no sibling differentiation needed, the description is remarkably complete. It covers return types (GeoJSON, list, both), boundary delivery options, pagination, determinism (payload.table/exports), meta-field selection, and follow-up signals. It even includes a concrete example prompt. The only minor gap is not explicitly listing every parameter default, but the schema covers that.

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 description adds meaning beyond the schema for many parameters. It explains boundary_delivery ('reference' returns a TIGERweb URL, 'inline' returns full GeoJSON), response_profile options, campus_list_format impact, campus_meta_fields usage, and pagination semantics. With 69% schema coverage, the description compensates well by explaining the intent and output behavior of key parameters, especially those controlling payload size and format.

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+resource+scope: 'Spatial containment query using teadata boundary methods; returns GeoJSON (district polygon + campus points) with overall_rating_2025 in properties.' This precisely identifies what the tool does and the output format. It also provides usage examples like 'within Austin ISD boundaries' or 'show on a map,' which clearly tie the tool to its intended prompts. Although it doesn't explicitly name sibling tools, it effectively differentiates itself by covering the general boundary-query use case that siblings might specialize in.

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 gives explicit when-to-use guidance: 'Use for "within Austin ISD boundaries" or "show on a map" prompts; apply status or campus_query filters (e.g., IDEA, KIPP).' It also explains how to handle pagination and follow-up calls: 'if payload.completeness.needs_follow_up or pagination.has_more is true, follow next_tool_call before finalizing.' This provides clear context for selection and invocation, even without naming alternatives explicitly.

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