List majors by lifetime ROI

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.