Launch529: 529 plans and college costs

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real context beyond that: the response includes the qualification plus a reason, and is grounded in IRS Publication 970, telling the agent the output is an authoritative determination rather than a bare boolean.

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?

One sentence, front-loaded with the action ('Say whether a college expense is a qualified 529 expense'), with parenthetical examples and the citation trailing. No filler; every clause carries 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 one-parameter, read-only lookup with no output schema, the definition gives enough to invoke correctly: input semantics, the determination returned, and its source. It does not describe the exact shape of the result (boolean vs. text, edge cases like 'no' answers), a minor gap given 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 single parameter has 100% schema coverage ('What the money was spent on'), which sets a baseline of 3. The description goes beyond it by listing representative values ('laptop', 'off-campus rent', 'gas', 'student health insurance'), showing the expected granularity and vocabulary of the input, which is genuinely useful for a free-text field.

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?

States a specific verb and resource: decides whether a college expense is a qualified 529 expense. Concrete input examples ('laptop', 'off-campus rent') and the authority (IRS Publication 970) make the scope unmistakable, and no sibling tool (compare_529_plans, get_529_plan, estimate_college_cost, school lookups) does anything similar, so it is trivially distinguishable.

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 the use case through examples but never states when to call this versus alternatives, nor any exclusions or prerequisites (e.g., jurisdiction, per-student limits). With no directly competing sibling, implied usage is tolerable but the routing guidance is thin.

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 openWorldHint=false, so the safety profile is fully covered. The description adds which attributes are compared (fees, ratings, tax benefit, minimums, eligibility), which is useful context about output content, but says nothing about return format or how missing/invalid plan slugs are handled.

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?

A single well-formed sentence that front-loads the verb and resource, then lists the differentiating comparison dimensions. No filler, no 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 one-parameter read-only tool whose annotations cover safety and whose only parameter is fully described in the schema, the description covers scope and compared attributes adequately. It could be tighter by noting the output shape, but nothing critical for correct invocation is missing.

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% and the input schema already documents the single parameter ('Plan slugs or names' with minItems 2 / maxItems 4). The description's 'two to four' simply restates those schema constraints, adding no new semantic detail such as slug format or ambiguity resolution between names and slugs.

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?

States a specific verb (compare), resource (529 plans), cardinality (two to four), and the comparison dimensions (fees, ratings, tax benefit, minimums, eligibility). The comparison framing clearly distinguishes it from siblings like get_529_plan (single plan) and list_529_plans (enumerate).

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?

Usage is implied by the verb: call this when you want plans side by side. However, it names no alternatives (get_529_plan / list_529_plans) and gives no guidance on when a single-plan lookup would be preferable to a comparison, so the agent must infer the routing.

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, non-destructive, closed-world behavior, so the description's job is to add context — and it does: it discloses the projection assumptions (steady returns after plan fees) and that the monthly figure is the amount that would fully fund the goal from today. It stops short of covering failure modes (e.g., invalid school id) or how fees are sourced.

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 tight sentences: purpose first, required inputs second, return values and modeling assumption last. No filler, and the most decision-relevant information is front-loaded.

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 usefully names the return values (per-year cost, total cost, monthly funding amount) and the modeling assumption, which is enough for an agent to invoke and interpret it. The one loose end is 'the plan's fees' — no plan parameter exists, so it is unclear which fee schedule is applied.

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 all seven parameters, making 3 the baseline. The description adds a marginal clarification by framing returns as net of 'the plan's fees', which reinforces the schema's 'before fees' note on annual_return_percent, but it adds no syntax or format detail 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 states a specific verb and resource ('project what college will cost and what to save') and enumerates the outputs (projected cost per year and total, monthly funding amount), so the agent knows exactly what this tool produces. It does not explicitly differentiate itself from siblings like compare_529_plans or get_529_plan, though the cost-projection framing is fairly distinct.

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?

It gives an input precondition ('Give a US school id and the year the student starts'), which implies the usage context, but it never states when to prefer this over compare_529_plans or how it relates to get_529_plan. Usage is inferable rather than explicit; no exclusions or alternatives are named.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds useful scope about what data is returned, but says nothing about return format, error behavior, rate limits, or authentication needs. It adds some context beyond annotations but not rich behavioral detail.

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 tight sentences: the first front-loads the returned data categories, and the second gives parameter sourcing advice. No filler, and the most important information (what you get) is first.

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 read tool with one required parameter, no output schema, and full annotation coverage, the description is nearly complete: it tells the agent what data will come back and how to supply the plan identifier. It omits error handling or response structure details, but those are minor given the straightforward nature of the operation.

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%, and the schema already explains the parameter accepts a slug or part of a name. The description adds practical provenance by specifying that the slug should come from list_529_plans, which is not present in the schema and helps the agent obtain a valid value.

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 comprehensive details for a single 529 plan and enumerates the specific data categories (fees, minimums, investment options, ratings, state tax benefit, restrictions, features). It implicitly distinguishes from list_529_plans by saying 'one 529 plan' and by referencing that tool for slugs, though it does not mention compare_529_plans.

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 practical hint for supplying the parameter ('Use the slug from list_529_plans, or the plan's name'), which implies the tool is used after listing. However, it gives no explicit guidance on when to choose this tool over compare_529_plans or check_expense, and no when-not conditions.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful payload context (historical depth back to 2005, income-banded breakdown) that tells the agent what data volume and shape to expect, though it says nothing about failure modes for an invalid id.

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 dense sentences with zero filler; the return contents come first and the id-sourcing prerequisite is front-loaded at the end where it's immediately actionable.

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 return-value burden and discharges it by listing the concrete fields returned. For a single-param read tool, nothing an agent needs in order to call it correctly is absent.

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% and the single parameter's own description already says 'The school's id from search_schools', which the description merely echoes. Baseline 3 applies since the schema does the work and the description adds no format or validity detail beyond it.

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?

States a specific verb and resource (details for one US school by id) and enumerates the exact data returned: sticker price, net price by income, cost history since 2005, graduation rate, median earnings. This clearly separates it from search_schools and the estimate/compare siblings.

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 routes the agent to search_schools for the required id, establishing the prerequisite workflow. It does not state when-not to use it or how it differs from estimate_college_cost, so it stops short of full alternative coverage.

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 cover safety (readOnlyHint, idempotentHint, non-destructive, closed-world), so the description's added value is the disclosure that results are ordered by popularity and ratings and that each entry carries fee, rating, tax-benefit, and nonresident fields. It adds real behavioral context beyond the annotations, though it says nothing about result size behavior or truncation beyond what the schema's limit documents.

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 purpose and result contents followed by the filter surface; no filler. The first sentence is dense but every clause carries 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?

With no output schema, the description usefully enumerates what comes back (fees, both ratings, tax benefit, nonresident eligibility), so an agent can judge relevance. It stops short of describing ordering ties, pagination, or what an empty filter result looks like, but it is adequate for a read-only listing 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 description coverage is 100%, so the schema already defines every parameter including defaults and examples. The description's filter summary largely restates those fields, adding only a soft semantic link ('minimum rating' for top_rated); 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?

States a specific verb and resource ('List state 529 savings plans') and immediately characterizes the result set: ranked by popularity and ratings, with fees, Morningstar/Saving For College ratings, tax benefit, and nonresident eligibility. It does not explicitly differentiate itself from close siblings like get_529_plan (single plan) or compare_529_plans, though the list/filter framing implies it.

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 second sentence enumerates the available filter axes (state, open-to-anyone, max fee, minimum rating), which implies when each is useful, but there is no explicit when-to-use guidance and no routing away from the sibling comparison or single-plan tools.

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, idempotent, non-destructive and closed-world behavior, so safety is covered. The description adds substantive non-annotation context: the geographic/eligibility scope and the exact return payload (id, location, annual published costs). It omits pagination or result-count limits, which keeps it from a 5.

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 tight sentences: capability and scope first, then return fields, then the sibling hand-off. No filler and every clause conveys actionable 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?

With no output schema, the description correctly compensates by listing the returned fields. Combined with the scope constraint and follow-up route, an agent has everything needed to call it and use the result.

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% and there is a single parameter already documented as 'part of the school's name'. The description's 'by name' adds the same meaning without extra syntax or matching guidance, so the 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?

States a specific verb (find) and resource (colleges and universities), and bounds the scope to US plus 529-eligible schools abroad. It is clearly distinguishable from the sibling get_school, which is explicitly named as a different lookup.

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 routes the agent: 'Use get_school with the id for cost history and net price,' establishing a clear follow-up alternative. It lacks an explicit when-not-to-use statement, so it falls just 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.