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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by stating that responses include payload.table and payload.exports for deterministic tables and CSV/JSON export. This goes beyond the annotation coverage and clarifies the output format.

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 concise, two sentences, and well-structured. It front-loads the core purpose and usage, then mentions the optional parameter and response format. No unnecessary words or repetition of schema info.

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 the tool's low complexity (2 simple array params), good annotations, and no output schema, the description is complete enough. It covers what the tool does, when to use it, the optional parameter, and the response payload structure. Minor gaps like explaining 'meta' keys are acceptable.

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 100% for both parameters. The description adds only marginal meaning ('extra comparison dimensions' for meta_fields) and a usage hint for identifiers, but the schema already provides the core semantics. Baseline 3 is appropriate since the description does not significantly enhance parameter understanding beyond the schema.

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 clearly states the tool's function: comparing 2+ campuses side-by-side on specific dimensions (rating, enrollment, staffing, demographics). It distinguishes from sibling tools by specifying multi-campus comparison and mentions the use of identifiers collected via search, setting it apart from single-campus detail tools.

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 the tool ('benchmarking or compare these campuses prompts') and provides a workflow prerequisite ('after collecting campus identifiers via search'). It does not name alternatives or specify when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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.

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

Annotations already declare read-only and idempotent, so the bar is lower. The description adds substantial behavioral detail: returns GeoJSON and a TIGERweb download URL, uses response_profile and campus_list_format to control output, paginates via cursor/next_cursor, and provides payload.table/exports plus a completeness.needs_follow_up flag. This goes well beyond the annotations without contradicting them.

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 longer than a few sentences but every sentence earns its place: example, default rationale, pagination, and output formats. It is front-loaded with the core purpose and remains organized, though slightly dense.

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 compensates by explaining key response behaviors: GeoJSON for maps, boundary_delivery modes, pagination fields, deterministic table/export payloads, and the follow-up condition. This is comprehensive for a moderately complex tool with 12 parameters.

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 describes 9 of 12 parameters (75% coverage), but the description adds meaning by giving a worked example for district_identifier and campus_query, explaining boundary_delivery's tradeoff, and clarifying how response_profile and campus_list_format affect output. This compensates for the slight coverage gap and enriches default choices.

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?

Description clearly states the tool finds charter-only campuses within a district boundary, specifically positioning it as a 'shortcut' and noting it returns GeoJSON. This distinguishes it from siblings like find_campuses_in_district_boundary and map_campuses_within_district by narrowing to charter-only campuses.

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?

Provides a concrete example (Austin ISD with campus_query 'IDEA') and explains default behavior (boundary_delivery='reference' to avoid huge payloads). It does not explicitly name alternative tools or when not to use it, but the shortcut phrasing and example give clear context for when this is appropriate.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral context by explaining that the tool computes aggregates rather than listing raw records, and mentions specific aggregate types. It does not contradict annotations, and this additional context is useful beyond the structured hints.

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 concise: two sentences covering purpose, examples, and filter compatibility. No redundant phrases, and the most important information (purpose) is front-loaded. Every sentence 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?

For a read-only aggregate tool with 4 optional parameters and no output schema, the description sufficiently covers the tool's behavior and return value concept (aggregate stats). It could be slightly more detailed about the exact structure of the response, but the given examples make it adequate.

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 75% (3 of 4 params described). The description adds meaning by mapping natural language examples ('all charter schools' = status=charter, 'A-rated campuses' = rating=A) to the filter parameters, which helps the agent translate user queries. This goes beyond the schema descriptions and compensates for the missing status description.

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 clearly states the tool's purpose: 'Compute aggregate statistics (total enrollment, rating distribution, etc.)' for campuses. It distinguishes itself from siblings like search_campuses by focusing on aggregate results rather than raw data, and provides concrete example questions.

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 with example questions ('Total enrollment of all charter schools') and refers to search_campuses for filter compatibility. However, it does not explicitly say when NOT to use this tool (e.g., when individual campus records are needed), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, destructiveHint=false. The description adds context by reinforcing that data is local and not to search the web, which aligns with openWorldHint=false. It does not describe error handling or response format, but given the strong annotation coverage, the added context is valuable.

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 three sentences, front-loaded with the primary purpose, followed by important usage caveats and a helpful example. No wasted words, though the example could be seen as slightly extra, it strengthens clarity.

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 campus detail lookup tool with no output schema, the description lists the major data categories returned, provides usage guidance, and points to a sibling tool for additional fields. It does not detail the response structure or meta_fields behavior, but the description is adequate for the tool's simplicity and aligns with the high schema coverage.

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 100%, so the schema already documents both parameters fully. The description adds an example ('Show details for campus 227901001') which illustrates usage of the identifier parameter but does not add semantic meaning beyond the schema. Baseline 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 clearly states the tool returns a campus profile with a specific list of data categories (Staffing, Class Sizes, Demographics, etc.), using the specific verb 'Return' and resource 'campus profile'. It does not explicitly differentiate from sibling tools like get_campus_aggregates, but the detailed list of metrics and the pointer to get_data_fields help define its specific scope.

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 provides explicit guidance to use get_data_fields for additional metrics, and instructs not to search the web since data is provided locally. This gives clear context on when to use this tool versus alternatives, though it does not exhaustively compare with all siblings.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations by stating it 'returns a list of keys' with a concrete example and clarifies the source ('local database'), which helps set expectations without repeating annotation info.

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?

Two sentences, front-loaded with the primary purpose, followed by usage context and return format. Every sentence earns its place with no redundancy or 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?

For a simple two-parameter discovery tool without an output schema, the description covers purpose, usage, return structure, and an example. It could theoretically mention pagination or limitations but is sufficient for the tool's complexity.

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 has 100% coverage with clear descriptions for both parameters (identifier, entity_type). Description adds an example key format but does not add new meaning beyond the schema, so baseline 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?

Description uses a specific verb ('Inspect') and resource ('available data fields') with clear scope ('for a campus or district'). It distinguishes itself from sibling data-retrieval tools by framing this as a discovery step for metadata, not data itself, and explicitly mentions 'before searching the web'.

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?

Provides explicit when-to-use guidance: 'Use this tool to discover what specific data points are available in the local database before searching the web.' It also clarifies how results feed into other tools ('requested via meta_fields in other tools'), making the workflow context clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description only needs to add context beyond that. It adds wildcard support and a local data source note, but it does not describe output format or pagination behavior. This is adequate but not rich.

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 somewhat long (four sentences plus an example) but every sentence adds value: purpose, usage, limitation, and example. It is front-loaded with the core function and reasonably concise for the information conveyed.

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 the tool's simplicity (2 params, no output schema) and strong annotations, the description covers the essential behavior and usage context. It gives examples and directs users to other query types, though it could mention the return format more explicitly. Overall, it is complete for a basic lookup tool.

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 100%, but the description adds meaning by explaining wildcard syntax for the identifier and clarifying that meta_fields requests additional metrics. This goes beyond the schema's minimal 'District name or number' and 'Optional list of district meta keys'.

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 clearly states the tool looks up a Texas school district by TEA number or name, with specific wildcard support. It distinguishes itself from siblings by framing it as an anchor for district-level questions and a provider of identifiers for other query types, making its purpose unambiguous.

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 provides clear guidance on when to use this tool: to anchor district-level questions or supply identifiers for detail, boundary, or campus list queries. It explicitly warns against using web search for basic info, but it does not name specific sibling tools as alternatives, which would elevate the score.

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

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

Adds rich behavioral context beyond annotations: pagination via cursor/next_cursor, include_total flag, meta_fields options, payload.table/exports, and follow-up requirements when needs_follow_up or has_more is true. Consistent with readOnlyHint, openWorldHint=false, and idempotent 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?

Though detailed, every sentence serves a purpose: usage example, local data assurance, pagination mechanics, response structure, and follow-up instructions. The structure front-loads the core purpose and then layers essential operational details.

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 compensates by detailing payload.table, exports, and pagination/completeness fields. It provides enough information for an agent to know what to expect and when to make follow-up calls.

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 100%, but the description explains how cursor and include_total work together for pagination, and the purpose of meta_fields/campus_meta_fields. This adds meaning beyond the raw schema definitions.

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 'Return district summary plus its campuses' and provides a concrete example, clearly identifying the resource and scope. This distinguishes it from siblings like get_district (which likely returns only district data) and search_campuses (which is campus-centric).

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?

Explicitly states when it's useful ('show all campuses in Houston ISD' style prompts) and instructs not to search the web. However, it does not explicitly name alternative sibling tools for cases where district context is unnecessary, leaving some room for ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable context beyond annotations by specifying the data source ('local teadata snapshot') and the response element ('geometry_fields'), which indicates what the output will include. This enriches the agent's understanding of the tool's behavior.

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 two concise sentences plus an example. The first sentence states the core function, the second provides usage context, and the example clarifies a typical query. There is no redundant or extraneous information.

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 simple tool with two well-documented parameters and comprehensive annotations, the description covers the essential aspects: what it does, when to use it, and what the response includes (geometry/location data and geometry_fields). There is no output schema, but the description compensates by mentioning the key output attribute. It could be more complete (e.g., specifying the exact response format), but it is sufficient for the tool's simplicity.

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 input schema already provides full descriptions for both parameters (identifier and entity_type), with 100% coverage. The description does not add new parameter-specific details, but the example ('What geometry fields does Austin ISD expose?') implicitly illustrates how to use the parameters. Since schema coverage is high, 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 clearly states the tool's function: 'Fetch campus or district geometry/location data from the local teadata snapshot.' It specifies the resource (campus/district geometry) and the action (fetch), and even notes the inclusion of 'geometry_fields' to indicate available attributes. This differentiates it from sibling tools like get_district or get_campus_detail, which focus on other data types.

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 this for map/boundary questions or to confirm geometry before drawing.' This clearly identifies suitable scenarios. However, it does not explicitly mention when not to use it or name alternative tools for non-geometry queries, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds substantial behavioral detail beyond that: pagination via cursor/next_cursor, include_total for total_matches, response shape with payload.table and payload.exports, and the need to follow next_tool_call when completeness.needs_follow_up or pagination.has_more is true. This is rich, non-redundant context.

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 front-loaded with purpose, then provides an example, pagination behavior, and follow-up instructions. Every sentence adds value and is tightly written, covering many important aspects without unnecessary verbosity.

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?

Despite having no output schema, the description explains the return structure (payload.table, payload.exports, distance_miles, flags), pagination mechanics (cursor/next_cursor, include_total), and important edge cases (needs_follow_up, has_more). This is complete for a 7-parameter tool with zero required parameters and no output schema.

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 100%, so the baseline is 3. The description adds an example that implicitly uses latitude/longitude and radius_miles, and mentions include_total for pagination awareness, but does not go into parameter-level syntax beyond what the schema already provides. It does not compensate much extra for the parameter details already present.

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 and resource: 'Find campuses within a radius (miles) of a campus or coordinates.' It clearly distinguishes this tool from siblings like search_campuses or find_campuses_in_district_boundary by emphasizing radius-based geospatial search, and it also notes the return of distance_miles and charter/private flags for filtering.

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 provides clear context for when to use the tool via an example ('coords (-95.36, 29.83) with radius 10 to find nearby charters') and explains pagination and follow-up behavior. However, it does not explicitly state when NOT to use it or name alternatives, though the sibling list makes the niche clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the metric list and mapping coordinates but no additional behavioral context such as response format or data source limitations. It does not contradict annotations and adds moderate value beyond structured fields.

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 two sentences, front-loaded with the core purpose, then enumerates specific metrics and a usage scenario. Every word earns its place with no redundancy or 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?

With no output schema, the description carries the burden of explaining return value. It lists the key metrics including coordinates for mapping, making the return type fairly clear. However, it could mention whether the result is a single object or array, or how to interpret the metrics, but for a dashboard tool this is adequate.

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?

There are zero parameters, so the description has no burden to explain parameters. The baseline of 4 applies, and no additional parameter details are needed. The description focuses on what the tool returns rather than inputs.

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 clearly states the tool returns campus-level staffing metrics for dashboard analysis, listing specific metrics like teacher experience, turnover rate, and student-teacher ratio. This specific verb+resource combination distinguishes it from siblings like get_campus_aggregates, which likely covers broader aggregate data.

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 instructs to use this tool for comparing staffing differences between charter and traditional campuses without web search, providing a clear use case. However, it does not explicitly mention when not to use it or name alternative tools, so it falls slightly short of full guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no extra behavioral context like response format, rate limits, or auth requirements, so the baseline 3 is appropriate.

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?

Two sentences, front-loaded with the action and use case. Every word earns its place; no filler or redundancy.

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 one optional parameter, rich annotations, and no output schema, the description provides enough context. It could describe the guide's structure more, but not needed for basic invocation.

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 covers the single 'topic' parameter fully with its description. The tool description adds no additional parameter meaning, matching the baseline for high schema coverage.

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 verb 'Return' and resource 'prompt-to-tool guide' clearly state what the tool does. It distinguishes itself from sibling data tools by being a meta-tool for tool selection, not a data query.

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?

Explicitly states when to use: 'when the user asks for a map, boundary, comparison, or spatial query.' It does not mention alternatives or when not to use, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context by detailing the return format (Sankey, map-ready, shares, shifts, distances) and optional scoping behavior, which goes beyond the structured fields. No contradictions.

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?

Two sentences: the first defines purpose and outputs, the second provides usage guidance. It's front-loaded, with no redundant words or 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 what the tool does, the nature of outputs, and when to use it. With 6 optional parameters and no output schema, it gives sufficient context for an agent to invoke it correctly, though it doesn't detail parameter interactions or output structure beyond the listed components.

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 100%, so each parameter already has a description. The tool description only mentions 'district or campus query,' aligning with existing parameters but not adding new depth beyond what the schema provides.

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 starts with a specific verb+resource: 'Analyze outbound student transfer flows across campuses.' It enumerates concrete output types (Sankey nodes/links, map-ready flow lines, charter vs traditional shares, rating shifts, distance patterns) which fully distinguish it from sibling tools that focus on districts, campuses, or boundaries.

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 'Use this for transfer dynamics, school choice patterns, or charter share questions,' providing clear usage context. It doesn't name alternative tools or exclusions, but the unique transfer focus among siblings makes it obvious when to use this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds substantial context beyond this: response_profile defaults to 'map', pagination via cursor/next_cursor, payload.table and payload.exports for list outputs, and the payload.completeness.needs_follow_up behavior. It also mentions the boundary_reference download_url. 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?

The description is moderately long but every sentence adds value: purpose, when-to-use, response profile, pagination, export behavior, follow-up logic, and an example. It is front-loaded with the purpose and maintains efficient structure without redundancy.

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 13 parameters and no output schema, the description covers the key output characteristics (campus points, boundary_reference URL), pagination, response profiles, exports, and follow-up handling. This is sufficient for an agent to invoke the tool correctly and interpret the response.

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 69%, so the description bears some responsibility. It supplements the schema by clarifying that response_profile defaults to 'map' for compact GeoJSON-only responses, that campus_list_format compacts list outputs, and that pagination uses cursor/next_cursor. It does not explain all parameters (e.g., limit, include_geojson) but adds meaningful context for the most important ones.

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 clearly identifies a specific verb+resource: it shows campuses on an interactive map within a district boundary. It also distinguishes itself as a 'map-focused alias' for within-boundary queries, differentiating it from sibling tools like find_campuses_in_district_boundary and map_charter_campuses_within_district.

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?

Explicitly states when to use it: 'Use this when the user asks to show campuses on an interactive map.' It does not name alternatives directly, but the word 'alias' implies a non-map counterpart, and the example 'Show campuses within Austin ISD on a map' gives clear context. Missing explicit when-not guidance keeps it from a 5.

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

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

The description discloses significant behavioral traits beyond the annotations: response_profile defaults to 'map', pagination via cursor/next_cursor, payload.table/exports for list outputs, and the need to follow next_tool_call when payload.completeness.needs_follow_up is true. This adds substantial context about response handling and limits.

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 dense but efficient; each sentence adds unique, critical operational information. It is structured logically: purpose, example, defaults, pagination, output formats, and follow-up instructions. No redundancy or 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?

Given the lack of an output schema, the description does a solid job explaining response behavior: pagination, map/list modes, exports, and follow-up calls. It could be more explicit about the exact GeoJSON structure or payload shape, but it provides enough detail for an agent to start using the tool effectively.

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?

While the schema already covers most parameter descriptions (75% coverage), the description adds clarity to response_profile (default 'map' for compact GeoJSON), campus_list_format (compaction control), and cursor (pagination). It does not systematically explain all 12 parameters, but the added value pushes it to the baseline 3.

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 clearly states the tool's purpose: a map-focused alias for charter-only campuses within a district boundary. It includes an explicit example prompt and distinguishes it from siblings like find_charter_campuses_within_district by emphasizing the map-oriented response_profile.

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 provides a concrete use case with an example prompt and explains when to use this tool (when an interactive map of charter campuses is desired). It does not explicitly mention alternatives or exclusions, but the guidance is clear enough for an agent to choose appropriately.

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

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

Annotations already declare readOnly/idempotent/destructive hints; the description adds valuable behavioral context about pagination (cursor/next_cursor), total_matches via include_total, response structure (payload.table, payload.exports), and follow-up via next_tool_call when completeness or pagination flags are set.

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 detailed but every sentence provides operational value: search filters, examples, tool distinction, pagination, response structure, and follow-up handling. It is appropriately proportioned to the tool's complexity, though slightly longer than the minimal ideal.

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 8 optional params and no output schema, the description covers essential aspects: what the tool returns (basic info, payload.table, payload.exports), pagination behavior, and when follow-up is needed. It fully equips an agent to invoke and interpret results 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 coverage is 75%, so the description compensates by explaining filter semantics with concrete examples (IDEA, KIPP, Austin ISD), clarifying cursor as a skip offset, and describing meta_fields and include_total, adding meaning beyond the schema.

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 clearly states the tool searches campuses by name/number/district with filters for status, rating, and grade_level, and explicitly distinguishes it from get_campus_detail by noting it returns basic info for identifier fetching before detail/compare/map calls.

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?

Provides explicit when-to-use guidance: use this to fetch identifiers before detail/compare/map calls, and use get_campus_detail for full stats. Also explains pagination usage, include_total, and meta_fields, giving clear context for alternatives.

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