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

With no annotations, the description fully discloses the tool's behavior: it returns ranked lists (top 15 per state or top 1 per state), filters by resident pricing, and uses a specific metric (30-year NPV). This is comprehensive for the tool's simplicity.

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 with no wasted words. The first sentence defines the resource and ranking, the second specifies usage. Information is front-loaded and efficient.

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 one optional parameter and no output schema, the description adequately covers behavior and output scope. It explains the ranking metric and the two modes. A minor gap is what 'best-value' precisely means beyond NPV, but it's sufficient for selection.

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 already describes the 'state' parameter (two-letter code). The description adds semantic value by explaining how omitting the parameter changes the output (nationwide summary) versus providing it (full list per state). This enriches the parameter's 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's purpose: listing each U.S. state's best-value four-year colleges ranked by 30-year NPV, with a clear distinction between passing a state (top 15) or omitting it (nationwide top pick). This distinguishes it from sibling tools like get_college or search_colleges.

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 on when to pass a state ('for its full list') and when to omit it ('for a nationwide summary'). While it doesn't compare to sibling tools, the usage context is clear and sufficient for a single-parameter 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?

With no annotations, the description carries the burden but only states the output contents. It does not disclose safety, side effects, or restrictions, though the read-only nature is implicit.

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?

Single sentence, front-loaded with key information, no unnecessary words.

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 zero parameters and no output schema, the description adequately lists return fields. Could mention how the data is used, but overall sufficient for a metadata endpoint.

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?

No parameters exist, so schema coverage is 100%. Baseline score of 4 applies; description adds no parameter info but none is needed.

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 it returns metadata for the underlying API, including specific fields like description, license, DOI, and endpoints. This distinguishes it from sibling tools which retrieve specific data (e.g., colleges, majors).

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 implies use for understanding API structure before using other tools, but does not explicitly state when to use this tool versus alternatives or provide usage context.

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?

No annotations provided. Description adds some behavioral context (accepts plain name and slugifies it), but lacks disclosure of error handling or output format beyond listing 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?

Two sentences: first sentence lists data fields concisely; second sentence adds slugification behavior and sibling tool reference. No fluff.

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?

Simple tool with one param and no output schema. Description covers input flexibility and enumerates output fields. Missing error behavior but overall 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 covers 100% of one parameter with a basic description. Description enhances by providing example slug format and stating it can also accept a plain name, adding clarity 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?

Description explicitly states it retrieves the full record for one college by slug, listing specific data fields. It distinguishes from sibling 'search_colleges' which is for discovering slugs.

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?

Clearly explains when to use (need full record for a specific college by slug) and when to use alternative (use search_colleges to discover slugs). Also notes it can accept a plain name and slugify it.

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?

No annotations are provided, so the description bears full responsibility. It details the data returned but omits behavioral traits such as read-only nature, auth requirements, rate limits, or error handling. This is a moderate gap given no annotation support.

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?

Three sentences: first states the core purpose and lists outputs, second clarifies slug acceptance, third directs to sibling for discovery. No fluff, all information 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?

Given one parameter and no output schema, the description is largely complete. It explains inputs and outputs thoroughly. Slight lack of coverage on error scenarios or read-only nature, but 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 coverage is 100% with one parameter. The description adds value beyond the schema by clarifying that the tool accepts a plain name and will slugify it, which is not obvious from the property 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 returns a full lifetime-ROI record for one major by slug, listing specific data points (ROI distribution, break-even age, etc.). It distinguishes itself from the sibling list_majors tool for discovering slugs.

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 says 'use list_majors to discover exact slugs', providing clear guidance on when to use which tool. Also notes that it accepts a plain name and will slugify it, setting expectations.

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?

No annotations; description carries full burden. Clearly states return fields (median/mean ROI, break-even stats, AI-exposure band) and behavior (compact rows, sorted by chosen field). No mention of destructive actions or auth, but for a read-only list this is sufficient.

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, no fluff. Front-loads the purpose and key details. Every piece of information 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?

No output schema, but description adequately explains return values (metrics listed). Covers main behavior and parameter nuances. Could mention pagination or default ordering more explicitly, but given the parameter descriptions are fully covered, it is nearly 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?

Schema coverage is 100% (baseline 3). Description adds value by explaining the broad-category vs subfield structure, sorting direction (descending for ROI, ascending for name), and that 'parent' filters subfields by category slug—going beyond what schema enums and descriptions provide.

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 it lists bachelor's-degree majors with lifetime-ROI stats, mentions two levels (19 categories, 115 subfields), and names the specific metrics. It also distinguishes from sibling tool 'get_major' by suggesting use of returned slug for full details.

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 tells agent to use the returned slug with 'get_major' for full detail, indicating when to chain calls. However, lacks explicit 'when not to use' or alternatives like 'search_colleges'.

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?

No annotations are provided, so description must carry full burden. It states the tool returns rankings with specific data per row (NPVs, tuition) but does not disclose read-only nature, data source, update frequency, or any side effects. Adequate but missing some transparency.

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: first covers purpose, second covers output content. No wasted words, appropriately sized.

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?

No output schema, but description explains return values (NPVs, tuition figures per row). However, it does not specify ordering direction (e.g., descending penalty) or the default sort. Mostly 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?

Schema description coverage is 100%, so parameter definitions are already complete. Description does not add meaning beyond schema; it only mentions what is included per row (output), not parameters. Baseline 3 applies.

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 it ranks U.S. public four-year colleges by out-of-state penalty, defines the penalty as NPV difference, and mentions included data (NPVs, tuition). This distinguishes it from siblings like best_value_colleges and search_colleges.

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 implies use when interested in out-of-state penalty ranking but does not explicitly state when to use this tool versus alternatives like best_value_colleges or search_colleges. No exclusions or when-not-to-use guidance provided.

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?

No annotations are provided, so the description carries full burden. It discloses the dataset scope (500 largest-coverage colleges), the returned columns, and the default sort. It does not mention side effects but the tool is clearly read-only. The description adds good behavioral context without contradicting any 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?

Two sentences, front-loaded with the main purpose and key columns, then filtering and sorting details. Every sentence adds value; no wasted words. The structure is clear and efficient.

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 no output schema, the description adequately explains return columns, filtering, and default sort. It also notes the slug usage with get_college. However, it does not mention the maximum limit (100) or whether results are paginated. It could be slightly more complete for a search tool with 5 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 description coverage is 60% (3 of 5 parameters have descriptions). The description adds meaning by explaining the filtering options ('Filter by name substring, state, and control') and the sort override behavior ('sorted by resident NPV descending unless overridden'). This compensates for the missing schema descriptions on control and sort_by.

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 what the tool does: 'Search the 500 largest-coverage U.S. four-year colleges'. It specifies the columns returned (NPV, cost, earnings, break-even age), filtering options (name, state, control), and the default sort order. It also differentiates from sibling 'get_college' by noting that the returned slug can be used with that tool.

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 implicitly guides usage by indicating when to filter by name, state, and control, and when to use the returned slug with get_college. However, it does not explicitly state when to prefer this tool over siblings like 'best_value_colleges' or 'out_of_state_penalty', nor does it provide exclusions or alternatives.

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