goldseam

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

Annotations already declare readOnlyHint=true, and the description adds tangible behavioral detail beyond that: 'Nothing is stored: the answer returns the package for the agent to keep,' plus the side-by-side reading behavior and the ambiguous-school 'nothing is read' rule. These are useful traits an agent cannot infer from the annotations alone.

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 front-loaded with the primary action, then explains data transformation, user interaction, ambiguity handling, and storage behavior. Each sentence contributes distinct information; no filler or redundancy. Its length is justified by the tool's complexity, and the structure is logical.

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 complex nested-object schema and the presence of an output schema, the description covers the necessary ground: what is read, how files are converted, how to handle ambiguous school names, user instructions, and the non-storage guarantee. It does not spell out every error condition or the output schema's content, but that is already available elsewhere.

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, but the description enriches parameter meaning by explaining what the tool does with each file ('each file's text and status, its courses and exams as rows') and how the data maps to what will_my_credits_transfer expects (courses as { unitid or school, code }; exams with score). This adds value beyond the schema's property descriptions.

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: 'Read a person's transcripts into their evidence package'. It then breaks down exactly what that means (file text/status, courses and exams as rows) and names the downstream sibling tool (will_my_credits_transfer). This clearly distinguishes it from the adjacent assemble_my_work_and_credentials and gives the agent an unambiguous sense of purpose.

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 operational guidance: ask the person for each transcript and its school, handle ambiguous school names by returning candidates and reading nothing, and send transcripts over multiple calls if needed. It does not name alternative tools to avoid or specify when not to use it, but the context and reference to will_my_credits_transfer make the intended scenario 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=true, and the description reinforces and expands on this by explicitly stating 'Nothing is stored: the answer returns the package for the agent to keep.' It also adds the behavioral note 'Ask the person for each file,' which implies iterative user interaction. These details go beyond what annotations alone provide and are consistent.

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 three sentences are purposeful and front-loaded: the first defines the operation, the second gives an instruction, the third clarifies scope and storage. No wasted words, though it could be slightly tighter if the 'This assembles; the Selfie is my_selfie_ksa_view' clause were merged earlier. Still, it reads naturally and is 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 the tool has an output schema (not shown but indicated) and the input schema fully describes parameters and size limits, the description covers the essential operational context: what to collect, the fact it is non-persistent, and the relationship to the selfie tool. It does not detail the return package structure, but that is handled by the output schema. This is sufficient for an agent to call the tool 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 100% and each parameter is already described in the input schema (e.g., content_base64 has size limits, package is described as the goldribbon_package_v1 object). The description adds high-level context about the overall package (text, status, credential signals) but does not materially improve per-parameter understanding beyond what the schema already provides. 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 states a specific action ('Read ... into their evidence package') and lists the exact resource types (resume, LinkedIn export, certificates, military, apprenticeship). It explicitly differentiates from the sibling tool my_selfie_ksa_view, making it clear this is the assembly tool, not the selfie view. This is distinctive and actionable.

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 a clear directive to 'Ask the person for each file' and notes that the selfie view is handled by a different tool. However, it does not explicitly mention the closely related sibling assemble_my_formal_education, so an agent might not know when to choose one over the other based on description alone. Still, the purpose is clear enough that the usage context is implied.

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 explicitly states 'Nothing is stored: the answer returns the package for the agent to keep,' and discloses that each entry is placed in a Selfie dimension by the KSA classifier or left unresolved and never defaulted. This adds meaningful behavioral context far beyond the readOnlyHint annotation.

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 and mostly free of fluff, with the core scoping front-loaded in the first sentence. The second sentence slightly restates the 'outside school/work' boundary, but each sentence still carries a distinct idea: what to record, whose statements these are, and that nothing is stored.

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 nested entries, a package object, and an output schema, the description covers the essential behavior: what counts as a life experience, classification into a Selfie dimension, no defaulting, no persistence, and returning the package. It does not explain what happens if the package is omitted, but the schema already documents the package and the output schema exists.

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 schema already documents each parameter. The description adds that entries are the person's own statements and are classified or left unresolved, but it does not add per-parameter meaning for weight, difficulty, life_period, or elaboration 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 opens with a specific verb-resource pairing: 'Record what a person says they have done outside school and work ... in their evidence package.' It enumerates concrete life-area categories and explicitly separates these from formal education, which distinguishes it from siblings like assemble_my_formal_education and assemble_my_work_and_credentials.

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 trigger condition is implied: use this when a person reports activities outside school and work such as family, clubs, or sports. The phrase 'kept apart from formal education' rules out formal-education use, but no sibling tools are named and no explicit when-to-use versus alternative guidance is 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?

The description adds very little beyond the readOnlyHint annotation — it only mentions that input SOCKS can be dashed with or without an .00 suffix. It doesn't explain the tool's output behavior, pagination, rate limits, or potential failure modes, which the annotation set doesn't already cover.

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 crisp clauses: a purpose question and the keying method with the format note. No filler, and the essential information is up front. It's a model of economical documentation.

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 single-required-parameter read lookup, the description is almost complete: it says what input key to use and implies the output is a list of certifications. A few more words about the response shape (element list, naming) might close the gap, but the tool name and question make that nearly self-evident.

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 description already defines what a SOC is and gives examples, so the description only needs a small addition. The note about the .00 suffix being optional is genuinely useful and not present in the schema definition, which adds real value for a user with a SOC code in either 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 is explicit: it asks what certifications serve an occupation and states the SOC-keyed lookup. It clearly distinguishes from siblings like certifications_for_program (which joins by program) and occupations_for_certification (reverse relationship), so there's no room to pick the wrong 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 implies the tool should be used when the user has a SOC code, but it never states alternatives or when not to use it. The 'don't know it? search by the job name' guidance is in the input schema parameter, which is a structured field rather than description text, so the description itself leaves usage boundaries implicit.

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 declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the behavioral trait that this is a 'broad, lower-precision' query, which is useful context about result quality. However, it does not disclose pagination behavior, result format, or any rate limits, which would add further 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 with no waste. The core purpose is front-loaded, and the precision caveat is stated efficiently. Every word 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 lookup tool with 100% schema coverage and no output schema, the description is nearly complete. It explains the tool's scope and precision trade-off. The only minor gap is that it doesn't mention what the response contains (e.g., a list of certifications), but the tool name and schema largely imply 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?

Schema description coverage is 100%, so the schema already documents all three parameters (cip, limit, offset) with examples. The description adds the conceptual framing that cip is a 'broad academic cross-reference' but does not add new parameter-level details 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 states a specific verb ('cross-reference') and resource ('instructional program (CIP)'), and distinguishes it from an occupation lookup. It is clear that this tool maps a CIP program to certifications, but it does not explicitly name the sibling tool certifications_for_occupation, so differentiation is implied rather than explicit.

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 says it is 'a deliberately broader, lower-precision question than an occupation lookup — never its peer (contract § 4).' This gives clear context for when to use it (broad academic cross-reference by CIP) and implies when not to use it (when a precise occupation lookup is needed). It does not explicitly name the alternative tool, but the contrast is clear enough.

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 only declare readOnlyHint=true, so the description carries most of the behavioral burden. It discloses significant output semantics: unresolved items are never guessed, source attribution is per-form rather than record-wide, and conditional fields appear only for multi-form/multi-source records. It does not cover pagination behavior or error cases, but adds useful context beyond the annotation.

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, jargon-heavy, and includes several run-on sentences that are hard to parse. While it is front-loaded with purpose, many details about forms, editions, and provenance arrive in a single undifferentiated block. Some phrases, such as the final Union explanation, could be trimmed without losing necessary agent guidance.

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?

There is no output schema, so the description must explain return values. It does so thoroughly, covering checklist id, award, group heading, source fields, and conditional version/source counts. Pagination semantics are left to the schema, and error behavior is omitted, but for a read-only list tool the description is largely 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 all three parameters are already documented in the schema. The description does not add meaning to learning_unit_id, limit, or offset beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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 purpose: finding which checklists require a given course. It clearly states the resource (checklists) and relation (requiring this course). However, it does not explicitly differentiate from siblings like find_checklists or get_checklist, relying instead on the tool name and 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?

Usage is implied by the purpose and by the note that forms come from the one-record get, not from this list. This gives a partial alternative for obtaining form details, but there is no explicit when-to-use guidance, no exclusions, and no named sibling alternatives.

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 only declare readOnlyHint, so the description carries real weight and delivers: source precedence (held rules first, then CourseAtlas read live), the 'comparable, never equivalent' semantics, and conditional output behavior (version_count/source_count/first_edition_seen only appear for multi-form records, and stale records self-report). It adds no auth, rate-limit, or error behavior, but the data-provenance disclosure is genuinely useful beyond the annotation.

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 length is defensible given there is no output schema and the row-shape rules must be conveyed somewhere, but the prose is convoluted and back-loaded: it opens with a rhetorical question and then stacks run-on clauses about FORM wording sources and edition spans. It is not clearly front-loaded, though little of it is pure 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 and a fairly complex, 9-parameter query, the description does the heavy lifting on returns: it explains row fields, the source-per-form rule, the conditional multi-form fields, and the stale-record case. The main gap is pagination/ordering behavior (limit/offset exist but only the schema explains them) and the absence of any alternative-tool routing beyond a passing mention.

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 nine inputs (code, title, school, unitid, direction, limit, offset, etc.). The description's detail is almost entirely about OUTPUT fields (source_url, band, version_count), not inputs, so it adds little input-side meaning beyond what the schema provides — 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 opening line ('Where does this course land at other schools, and what lands on it') and 'The published transfer rules for one course' make the resource and the direction of the query clear. However, the jargon ('the rules CourseShelf holds', 'band', 'FORM') obscures rather than sharpens the purpose, and no sibling tool is named for contrast, leaving the agent to infer how this differs from get_comparability or find_comparability.

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 only implied: the tool is for pulling transfer rules per course, and there is one routing hint ('The forms themselves ... come from the one-record get, never from a list') pointing to a sibling. There is no explicit when-to-use / when-not statement and no named alternatives among the ~50 siblings, so the agent must infer the boundary.

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 only declare readOnlyHint=true; the description adds a genuinely informative behavior: 'Each cell is copied or counted, never scored' and 'as published' nuance, clarifying that the tool presents data rather than evaluates it. This exceeds basic read-only disclosure.

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, action-first, with no wasted words. Each phrase ('bridge size', 'O*NET demand', 'evidence classes') 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 comparison tool with an output schema and readOnly annotation, the description sufficiently explains the comparison dimensions and the non-scoring behavior. The missing usage-vs-alternatives guidance is minor and does not prevent correct 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?

Schema description coverage is 100%, so the schema already documents both parameters with descriptions and examples. The description adds domain context by framing to_socs as 'destination occupations' and from_soc as 'one occupation', but it largely restates the schema semantics, 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?

The description uses a specific verb 'line up' and names the resource 'destination occupations' plus the exact attributes compared (bridge size, O*NET demand, evidence classes). It distinguishes itself from compare_program_checklists by focusing on occupation destinations rather than checklists.

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 tool is for comparing 2–6 destination occupations from a single source occupation, but it does not name alternative tools or state when not to use it. It gives clear operational context (what is compared) but no explicit exclusions.

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?

Goes well beyond the readOnlyHint annotation by disclosing output semantics: earnings are a lowest-to-highest range across publishing schools (never a computed median), six-digit majors draw earnings from their four-digit series and label them series-level, and every column is complete or names the unpublished figure. This is substantial behavioral context an agent cannot infer from annotations or schema.

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?

Front-loads the core question, then packs output-semantics detail into dense, purposeful sentences. Slightly heavy, but nearly every clause carries information about how figures are produced, so little is wasted.

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 an output schema present, the description need not restate return values, yet it usefully explains the range/series conventions behind them. Coverage of constraints and caveats is strong; the main gap is guidance on selecting this tool over sibling comparison or lookup tools.

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 majors, level, and state. The description only reinforces the 2-5 majors and single-level constraints and adds nothing about the optional state parameter's role beyond what the schema states. 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 (compare) and resource (majors) and enumerates exactly what is compared: definition, schools, O*NET jobs/outlook, and 1/5-year earnings with debt. The scope is clear and distinguishable from the school-oriented siblings, though it never names an alternative tool to route against. Strong but not maximally differentiated from sibling compare 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 constraints (two to five majors, single level) imply the comparison use case, but there is no explicit when-to-use, when-not-to-use, or named alternative such as find_my_major. Usage is implied rather than guided.

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?

Only readOnlyHint is provided, so the description carries the behavioral burden and does so richly: it states the comparison 'never ranks' and invents no score, that credits left is reduced 'only by items a school's own rules cover' and never by an unknown or inferred item, that payback is withheld and the missing input named when either input is unpublished, and that GoldCheck states/reasons are carried through unchanged. That is substantial disclosure beyond 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 opening hook is front-loaded, and nearly every clause carries a real rule (no ranking, credit reduction limits, payback guard, state passthrough) rather than filler. It is dense, em-dash-heavy, and reads as one long paragraph, which costs some readability, but little of the content is redundant.

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 an output schema present, return values need not be described, and the description still covers comparison scope, input-conditional behavior, and the key non-ranking constraint. The only material gap is explicit routing guidance against the other compare_ siblings, which the rich schema and annotations do not supply.

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 baseline is 3. The prose adds conceptual meaning for the optional 'held' input (what each school's published rules would count courses/exams for) and reinforces the 2-5 school bound, but 'package' and 'level' get no added semantics beyond the schema, so the description only marginally exceeds 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 names a specific verb and resource ('Which of these schools is better for me?') and pins the scope tightly: 'Two to five schools, one major and a level, side by side.' It also enumerates the compared dimensions (program, credits, requirements, cost, earnings, debt, payback), which sharpens what 'compare' means. It stops short of naming sibling tools such as compare_my_major or compare_destinations, so differentiation is implied rather than stated.

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 framing ('Two to five schools, one major and a level') and by the conditional 'when the person offers their courses and exam scores,' which quietly describes an optional input path. There is no explicit when-to-use versus when-not, and no named alternative among the four sibling 'compare_' tools, so the agent must infer 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?

Beyond the readOnlyHint annotation, the description discloses rich behavior: nothing is summed or computed, missing catalog data is stated as such, schedule is stated not held, each row names its source's wording via source_url/capture_file/catalog_year/source_catalog_name, and conditional version_count/source_count fields appear only for multi-form or multi-source records. It also explains how older editions are surfaced, which is valuable context not present in 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 extremely long, dense, and full of run-on sentences with repeated phrasing such as 'reads exactly as it always has' and 'because the Union keeps a record no current catalog prints.' Although it front-loads the purpose reasonably well, the remainder is over-specified for a tool description and hurts readability.

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 and a complex comparison behavior, the description covers the important dimensions an agent needs: source provenance, conditional return fields, missing-data handling, versioning, and pagination context. It is complete enough to call and interpret the tool 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 description coverage is 100%, so the schema already documents all four parameters, including detail, program, unitids, and institution_offset. The description reinforces UNITID and program matching but adds no syntax or constraints beyond the schema, so the baseline of 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 'Compare' and specific resources: a program's published checklist beside tuition and fee policy for each IPEDS UNITID. It also distinguishes itself from list-based siblings by noting the forms come from 'the one-record get, never from a list.' However, it does not explicitly contrast with nearby compare tools such as compare_my_school or compare_my_major.

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 operational scope (1 to 10 UNITIDs, 5 institutions per call, pagination via institution_offset) but no explicit when-to-use or when-not-to-use guidance relative to sibling tools. It implies multi-institution comparison but does not help the agent choose among alternatives like find_checklists, get_checklist, or compare_my_school.

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 mark readOnlyHint=true, so the safe read nature is established. The description adds meaningful behavioral detail: auto-detection of code family based on format (dotted vs dashed), acceptance of O*NET .00 suffix, and that it returns both codes and titles. It doesn't discuss pagination or error handling, but the added format/detection context goes beyond 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 exactly two sentences, front-loaded with a direct question that captures the tool's purpose, followed by precise technical details. Every word contributes meaning; there is 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 read-only lookup tool, the description covers the essential aspects: input family detection, accepted formats, and output content (codes and titles). The limit/offset parameters are documented in the schema, and no output schema is needed. It could mention invalid code behavior or explicitly note pagination, but those are minor gaps 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?

Schema description coverage is 100% for all parameters, so the baseline is 3. The description adds value by explaining the code family format (dotted CIP vs dashed SOC) and the O*NET .00 suffix acceptance, which are not fully specified in the schema's parameter description. This extra semantic detail helps the agent construct valid 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's function: it auto-detects whether the input is a CIP or SOC code and returns the corresponding codes and titles from the federal CIP-SOC crosswalk. It uses specific verbs ('cross', 'answers') and a clear resource ('federal CIP-SOC crosswalk'), distinguishing it from siblings like resolve_term or search_certifications.

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 clear context for when to use this tool: whenever you have a CIP or SOC code and need the other family's codes and titles. It does not explicitly name alternatives or provide exclusion conditions, but the context is strong enough that an agent can infer when this tool 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?

The description discloses key behavioral traits beyond the readOnlyHint annotation: the claims are drafts for the person to affirm or decline, the AI never affirms a claim, and nothing is stored because the package is returned to the agent. This richly explains the read-only and non-committal nature of the operation without contradicting the annotation.

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 with no fluff. The main action and prerequisite are front-loaded in the first sentence, the draft/affirmation behavior in the second, and the school hint and storage behavior in the third. 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?

Given the tool's complexity, the output schema, and the annotations, the description covers everything needed to invoke it correctly: the required input source, the output destination, the optional school's purpose, the no-storage guarantee, and the relationship to sibling tools. Nothing essential 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 coverage is 75%, and the description adds meaningful context for the required package parameter by specifying it comes after my_selfie_ksa_view. It also explains why the optional school should be supplied (to ready the catalog for suggestions), though the schema already covers much of this; language and aspiration are left to 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 opens with a specific verb and resource: 'Draft the credit claims a person's evidence supports, from their package.' It clearly distinguishes this from the upstream my_selfie_ksa_view and downstream suggest_credit_for_my_learning by positioning itself between them, leaving no ambiguity about what the tool produces.

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 context for when to call the tool: after my_selfie_ksa_view, and before suggest_credit_for_my_learning when the school is supplied. It does not explicitly state when not to use it or name alternatives, so it falls just short of a 5, but the workflow context is 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?

With readOnlyHint=true already covering the safety profile, the description adds real behavioral context: the traversal direction (upward, parent meaning), a strong guarantee that 'every step stays in the sense it started in', and disclosure of what each step returns (gloss plus synonyms). It lacks termination/error details (e.g., what happens when no KSA-mapped sense exists), so it is not a full 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?

Purpose is front-loaded in the first clause and the following sentences each add distinct information (traversal mechanics, sense stability, step payload). The rhetorical opener 'What is this word, upward?' is slightly gimmicky but still earns its place as a directional cue.

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?

There is no output schema, so the description correctly compensates by describing the per-step payload (gloss and synonyms). Combined with the direction and sense-stability behavior, an agent has enough to invoke it correctly, though edge-case handling for unresolvable or unmapped terms is unaddressed.

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% for the single term parameter, so the schema already carries the field meaning. The description adds a marginal grain of semantics by noting the term is anchored to a KSA-mapped sense, but gives no format, casing, or sense-selection guidance beyond that, 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?

The description names a specific verb (walks the is-a/hypernym chain) and the resource it operates on (the word's KSA-mapped sense), so an agent knows this moves from a term toward its broader categories. It does not explicitly distinguish itself from the sibling resolve_term, which is the most likely source of confusion, so it stops short of a 5.

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 rather than stated: the reader infers you call this when you want broader categories for a word. There is no explicit when-to-use, no when-not-to-use, and no naming of the alternative (resolve_term) that an agent would weigh against 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 only declare readOnlyHint=true, so the description carries the rest and does so well: it discloses the empty-result behavior ('Answers none held'), the conditional presence of version_count/source_count/first_edition_seen/last_edition_seen for multi-form records, and staleness reporting for records not printed by a current catalog. Pagination behavior is left unstated.

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 purpose is front-loaded, but the body sprawls across long, tangled sentences dense with undefined jargon ('the build', 'the Union', 'FORM', 'edition') that an agent cannot resolve from the text. Several clauses explain row shape in prose that would be better delegated to an output schema.

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 does attempt to cover return semantics, the empty case, and conditional fields, which is the right instinct. However, its opaque vocabulary and missing pagination/ordering behavior leave the agent with an incomplete and partly unparseable picture for a multi-record list 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 documents limit, query, offset and unitid. The description restates the query and unitid filters but adds no format or syntax detail (e.g., how title words are matched, whether UNITID combines with query), so it does not exceed the schema baseline.

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 opening question states a specific resource (articulation/transfer agreements) and its two filter axes (title words, institution UNITID as a party), which is a clear verb+resource. It also implicitly separates itself from the one-record sibling by noting that forms 'come from the one-record get, never from a list.' The garbled register ('the build holds none', 'current FORM') keeps it from a 5.

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 routing hint that forms are fetched via get_agreement and never from a list is genuine when-to-use guidance, but it is buried mid-paragraph and phrased indirectly. There is no explicit statement of when a caller should reach for find_agreements versus get_agreement, find_transfer_frameworks, or find_pathways among the many 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?

With only readOnlyHint available, the description adds substantial behavioral detail: it explains empty results, per-row source attribution, when extra fields like version_count and source_count appear, and when a record is retained despite no current catalog printing it. This is exactly the kind of edge-case and return-shape context annotations do not cover.

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 first sentence is front-loaded and most subsequent sentences carry necessary output-shape or edge-case information. The wording is dense and occasionally awkward, but the length is largely justified by the absence of an output schema.

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 list tool with no output schema, the description explains the key row semantics, source ownership, and multi-form/multi-source edge cases. It could do more to describe the response envelope or pagination behavior, but it covers enough for an agent to understand what comes back.

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 schema already documents unitid, limit, and offset fully. The description does not add parameter syntax, defaults, or usage nuances beyond the schema, so the baseline of 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 states the resource and scope clearly: published catalog editions held for an institution. It also distinguishes this list from the one-record form retrieval, though it does not name the sibling get_catalog explicitly and opens with a question rather than a direct verb-resource phrase.

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 clear routing context: forms with their own content and sources come from the one-record get, never from a list. This tells the agent when to use find_catalogs versus get_catalog for forms, but it does not list explicit exclusions or describe when another catalog-related sibling would be preferred.

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 only declare readOnlyHint=true, so the description carries most of the behavioral burden and does add real value: it explains that source_url/capture_file/catalog_year/source_catalog_name belong to a single form-source, that version_count/source_count/first_edition_seen/last_edition_seen appear only for multi-form or multi-source records, and that records last seen in older editions are flagged. This is unusually rich disclosure, though it is return-shape oriented rather than operation-shape.

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 purpose is front-loaded, but the body is a dense, comma-chained prose explaining edge cases ('one sentence saying so in words', 'reads exactly as it always has') that is hard to parse and repeats the single-vs-multiple distinction. It earns most of its length but not its readability.

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 must convey return structure, and it does so thoroughly for a conditional-response list tool, including pagination-relevant context indirectly via offset/limit in the schema. Given the tool's complexity, coverage is solid, with only minor ambiguity around how narrowing interacts with the full record.

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 unitid, query, program_id, limit, and offset. The description adds only marginal meaning (award words or program id 'narrow' results). Baseline 3 is appropriate when the schema does the heavy lifting.

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+resource (find the checklists an institution publishes) and even defines what a checklist is ('the generic itinerary of requirements for an award'). It also distinguishes itself from the one-record sibling by saying forms 'come from the one-record get, never from a list.' The question phrasing and dense asides slightly blunt the front-loaded clarity.

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 implies when to use narrowing parameters ('Optional award words or a program id narrow them; pass one to get_checklist') and routes agents to get_checklist for full form detail. However, the guidance is embedded in a run-on sentence, no explicit when-not conditions are given, and it doesn't state how it relates to compare_program_checklists or other checklist-adjacent 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?

With only readOnlyHint=true in the annotations, the description carries the behavioral load and does so: it explains that a single-form/single-source row reads as it always has while multi-form or multi-source rows gain version_count, source_count, first_edition_seen and last_edition_seen, and that stale records persist because the Union keeps records no current catalog prints. That is genuine beyond-annotation disclosure of response shape and edge-case 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 long and meandering, with awkward prose ("reads exactly as it always has") and the core purpose buried in a question before several sentences of edge-case detail. The routing note to the one-record get appears late, so the most decision-relevant information is not front-loaded and much of the middle could be tightened without loss.

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?

There is no output schema, so the description must explain returns, and it does cover row shape, conditional fields, and the stale-record case reasonably well. It is still unclear on the overall list contract (ordering, pagination behavior, what a row minimally contains when only one form/source exists), leaving the agent with an incomplete picture of what to expect for a 5-parameter list 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 baseline is 3. The description does add a small amount beyond the schema — clarifying that the learning unit may appear "as a source or substitute," where the schema only says "a course named in it" — but it says nothing about limit/offset pagination semantics beyond what the schema already documents, so the added value is marginal.

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 first sentence states the resource concretely — comparability bundles, glossed as published transfer rules — and the closing line differentiates it from the sibling one-record get ("The forms themselves ... come from the one-record get, never from a list"), establishing this as the list/find side. The verb is only implied by the question phrasing rather than stated, but an agent can still tell what it returns and how it differs from get_comparability.

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 names the three optional filters and tells the agent that an empty result is a valid answer ("Answers none held when the build holds none"), which is useful context. It also routes form-level retrieval to the one-record get. However, there is no explicit statement of when to prefer this tool over the close siblings comparability_for_learning_unit or get_comparability — the routing is inferred from one sentence rather than declared.

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 only declare readOnlyHint=true, so the description carries the burden of behavioral disclosure. It adds substantial context: what each row includes (source metadata, version counts, first/last edition seen), that forms themselves come from a separate get, and that older-edition records are flagged. This is rich beyond the annotation, though it doesn't cover pagination defaults, error conditions, or authentication needs.

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 overly long and digressive, burying the core lookup behavior under details about form sources, version counts, and catalog editions that are tangential to the primary find operation. It is not front-loaded with the essential purpose; the first sentence is a question, and key routing information appears late. Several sentences could be trimmed or moved to related tools.

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 and only a readOnly annotation, the description does provide extensive behavioral detail about return values (row contents, source metadata, version indicators). However, it misses practical completeness for a search tool: no pagination explanation beyond schema defaults, no result limit behavior, and no guidance on handling empty results. The heavy focus on form/source nuances is likely more relevant to get_institution, suggesting misdirected completeness.

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 five parameters with examples and defaults. The description adds interpretive value by explaining how parameters combine: query answers identity, state lists institutions, with no query/state it returns states with counts. This semantic integration goes beyond the schema's individual parameter descriptions, though it doesn't clarify parameter interactions like query+state or city+state.

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 conveys that this is a lookup tool for institutions answering by name fragment, IPEDS UNITID, or state, with sector and identifiers. However, the core purpose is buried under extensive detail about forms, sources, and versioning, making it harder to grasp quickly than a straightforward 'find institutions by X' statement. It doesn't clearly differentiate from sibling get_institution or find_programs, which likely retrieve a single record or related lists.

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?

There is no explicit guidance on when to use this tool versus alternatives like get_institution or find_programs. The description implies a search/listing function but doesn't state 'use this to discover institutions' or exclude cases (e.g., 'use get_institution for full details on one institution'). No when-not-to-use or sibling routing is 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?

Annotations only declare readOnlyHint=true, so the description carries the behavioral burden and does so well: it discloses that steps come only from agreement/pathway documents (never assembled from award levels), that every input is marked counted/not-counted/needs-review with nothing dropped silently, and that missing inputs are named rather than invisibly penalised. These are non-obvious guarantees that add real value beyond the safety hint.

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?

Roughly five sentences, mostly front-loaded by the framing question and the goal/inputs clause. It is dense but each sentence carries content; the rhetorical opener is mildly stylistic but does establish purpose quickly.

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 an output schema present, the description need not describe return values, yet it usefully explains the ranking transparency and gap-handling semantics an agent needs to interpret results. Combined with the readOnly annotation, the definition is close to complete, missing only explicit routing to sibling tools.

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 baseline is 3, but the description adds meaning to the 'held' input by enumerating what a person brings (courses, exams, Competency Selfie, work and life experience) beyond the schema's terse 'shape will_my_credits_transfer takes'. The remaining params are already fully documented in 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?

States a specific verb+resource: it returns ranked paths toward a goal (major or job) given what the person brings, and it explains the ranking rationale. It is clearly a personalized-ranking tool, but it never names or contrasts with the obvious sibling find_pathways, so sibling differentiation relies on inference.

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 goal-plus-inputs framing ('For a goal... and what the person brings'), which tells the agent when this is relevant. However there is no explicit when-not guidance, no prerequisites, and no alternative named (e.g., find_pathways vs. get_pathway), leaving the agent to infer 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?

With only readOnlyHint=true given, the description carries the behavioral load and does so richly: it discloses what each major returns, that words resolve through the KSA Dictionary and never by spelling match, that unmatched words return the closest Dictionary terms, that award-level completers flags are per-field and never summed, and that per-school IPEDS rows are not published (state count only). This is substantive disclosure well beyond the annotation.

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?

It is front-loaded with the driving question and the two input paths, then layers behavioral detail. The single long middle sentence is dense and somewhat baroque, but nearly every clause conveys behavior an agent can use, so the length is largely earned rather than padding.

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 six-parameter tool with an output schema, the description supplies the resolution logic, fallback behavior, and data-scope caveats an agent needs to call it correctly, and it need not restate return values. The only gap is the absence of explicit routing to sibling tools for adjacent tasks.

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 baseline is 3, but the description adds real meaning: 'words' resolve semantically via the KSA Dictionary (not literal matching), 'soc' pulls every crosswalk-linked major, and 'state' affects the stated school count rather than raw rows. It clarifies the semantics of the otherwise terse schema fields.

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+resource (find the majors answering a study question) and spells out the two input modes: a person's own words or a SOC job code. It is clearly distinct from lookup-style siblings such as find_programs or find_institution, but it never names an alternative tool explicitly, so it stops short of full sibling routing.

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 opening framing ('What should I study?') implies the use case and the accepted inputs, and the resolution rules hint at behavior. However, there is no explicit when-to-use / when-not, no prerequisites, and no pointer to alternatives like compare_my_major for side-by-side comparison, so guidance is only implied.

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 only supply readOnlyHint=true, so the description carries most of the burden and delivers: tri-state met/not-met/not-testable handling, filters only excluding on held facts, a stated ranking rule, no recommendations, and an explicit TODAY data-coverage limitation. It lacks auth/pagination behavior, but for a read-only match tool this is strong disclosure.

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?

It is front-loaded with the core purpose and every sentence carries information, but the dense run-on construction (multiple em-dash clauses per sentence) and mild repetition of the not-testable idea make it harder to scan than an equivalent bulleted or shorter form.

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 an output schema present, return values needn't be explained, and the description covers the candidate-set limitation, ranking behavior, and tri-state semantics for a 14-parameter tool. What is missing is explicit routing against the many sibling tools, leaving a small gap against the tool's apparent 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 coverage is 100%, so the baseline is 3, but the description adds real semantic meaning beyond the schema: cost_max does not remove schools lacking cost (they rank below as not testable), exclude_untestable's strict removal and reporting, and the national-and-says-so behavior with no state/city/place. These sharpen parameters that the schema describes only briefly.

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 with a clear scoping phrase: 'for a major and a level, the schools that award it.' The 'match-up, not a dump' framing implicitly sets it apart from list-style siblings like find_institution or find_programs, but no sibling is named outright, so it stops short of a 5.

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 opening 'Where can I study this?' and the required major/level pair imply when the tool applies, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many find_/compare_ siblings. Usage is inferred rather than directed.

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 only carry readOnlyHint=true, so the description carries most of the load and does it well: it discloses that the tool answers 'none held' for empty results, that source_url/capture_file/catalog_year/source_catalog_name belong to one form's source rather than the whole record, and that version_count/source_count/first_edition_seen/last_edition_seen appear only for multi-form/multi-source records. It does not cover pagination behavior or rate/limit implications, so it stops short of 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?

The description is a dense, run-on block heavy with idiosyncratic jargon ('the Union', 'the build holds none', 'reads exactly as it always has') that is difficult to parse for an agent. It is front-loaded on the filters and empty-result behavior, but several clauses repeat the same conditional-field idea instead of stating it once economically.

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 must explain return shape, and it does so in detail (row fields, conditional fields, source attribution, older-edition flagging), which is the correct burden for this tool. It omits any explanation of limit/offset paging beyond the schema's 'next_offset' hint, leaving a small gap.

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 five parameters; the description only restates the three filter dimensions as 'title words, an agreement id, or a checklist id' without adding format or syntax insight. Baseline 3 applies when structured data does the heavy lifting.

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 resource ('Which pathways are held?') and its optional filters, and it implicitly distinguishes itself from the sibling get_pathway by declaring 'The forms themselves ... come from the one-record get, never from a list.' The verb is implied rather than named (it is a filtered list/find), which keeps it short of a 5.

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 through the filter list and the routing note that per-form detail belongs to the one-record get, giving the agent a hint about when to reach for this tool versus get_pathway. There is no explicit when-to-use/when-not statement and no mention of the other find_* siblings (find_agreements, find_checklists) that overlap with the agreement_id/checklist_id filters.

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 only readOnlyHint=true from annotations, the description carries real weight: it discloses that an empty result means 'none held', that each row names its own source, and that version_count/source_count/first_edition_seen/last_edition_seen appear only for multi-form or multi-source records, plus that records from retired editions are flagged. These are substantive behavioral traits beyond the safety annotation, though the phrasing is hard to parse.

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 summary is front-loaded with the core question, but the paragraph is long and contains convoluted, near-redundant clauses ('reads exactly as it always has', 'one sentence saying so in words') that slow parsing without adding decision-relevant content.

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?

There is no output schema, so the description must describe return shape, and it does: rows, source attribution fields, conditional version/source fields, and the retired-edition flag. Combined with full schema coverage for inputs, an agent has enough to call and interpret the tool, despite the awkward prose.

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 all four parameters are already documented in the schema (limit default 20/max 100, offset = next_offset, unitid = IPEDS UNITID). The description adds only the query narrowing hint, 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?

The opening question ('Which academic policies does this institution publish...') plus the field list (transfer credit, prior learning, tuition and fees) names a specific resource and scope. It implicitly distinguishes itself from the singular 'one-record get' for individual forms, though it never names the sibling (get_policy) outright, so differentiation is only inferable.

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?

'Optional words narrow them' tells the agent how to filter, and 'The forms themselves... come from the one-record get, never from a list' routes the agent away from this tool for per-form detail. However, there is no explicit statement of when to prefer this tool, and the routing sentence is buried mid-paragraph.

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 only readOnlyHint true, the description carries the burden and discloses a lot: returned fields (award, CIP, credit figure, edition, source page, institution), conditional fields for multi-form/multi-source records, and the special note for records last seen in an older edition. It omits pagination or auth details, but adds substantial behavioral context beyond 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 bloated and convoluted, with long run-on sentences about forms and sources that obscure the core search purpose. Key information is present, but the structure is not front-loaded and several sentences could be merged or cut.

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?

There is no output schema, so the description must carry return semantics. It does explain the returned fields, conditional version/source metadata, and older-edition behavior in reasonable detail. It still leaves some search behavior and ordering unspoken, but is largely complete for an agent to call it.

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 six parameters. The description adds meaning for query and optional UNITID, but does not clarify city, state, limit, or offset 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 opening question states a specific verb and resource: find programs matching given words across institutions. It also distinguishes the list result from the one-record get for forms. However, it does not name the obvious sibling search_programs_and_learning_units or programs_for_institution, so differentiation is incomplete.

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 when to use it: searching programs by words, optionally scoped to one institution's UNITID. It also notes that forms themselves come from the one-record get, not from this list. But there is no explicit when-not-to-use or named alternative among the many search/find 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?

With readOnlyHint=true the safety profile is already covered, and the description still adds substantial behavior: conditional emission of version_count/source_count/first_edition_seen/last_edition_seen, source attribution rules, and the 'last seen in an older edition' case. No output schema exists, so this return-shape disclosure is doing real work, though it omits pagination/limit semantics beyond the schema.

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?

Purpose is front-loaded, but the prose is dense and some sentences are hard to parse ('reads exactly as it always has', 'the Union keeps a record no current catalog prints'). Most sentences carry information, yet the wording is more convoluted than needed for the content delivered.

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 must convey return structure, and it does so in detail for the conditional fields and source attribution. For a 3-param, zero-required list tool the coverage is close to complete, missing only explicit pagination guidance.

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 limit, query and offset. The description only loosely restates the query ('optional name or jurisdiction words') and adds nothing about limit or offset semantics, so 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 opening question states a specific resource (statewide/compact transfer frameworks) and the filtering inputs, and the later sentence 'come from the one-record get, never from a list' implicitly differentiates it from get_transfer_framework. It is clear but the phrasing is oblique rather than a crisp verb+resource statement.

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 (search/list with optional filters; returns 'none held' when empty) and the one-record alternative is named for retrieving forms. There is no explicit statement of when to prefer this over find_agreements, find_pathways, or the other find_* 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 declare readOnlyHint=true, and the description adds useful behavioral context: results contain only roads, no person data; sources are O*NET or credential mappings via CIP-SOC; bridges include credential conditions and programs; demand is as published by O*NET. This substantially clarifies the tool's data scope and privacy posture.

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 run-on sentence packed with specialized terms. It conveys a lot, but the nested structure and unexplained 'karat', 'CIP-SOC crosswalk', and 'nearest the state given' make it harder to parse than necessary.

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 output schema exists and all parameters are documented, the description covers the main output categories and explicitly disclaims person data. It could be more complete by mentioning the 'from' everyday-words alternative and how unspecified filters behave, but those gaps are largely covered by the parameter 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 description coverage is 100%, so the schema already documents all seven parameters. The description reinforces that from_soc is the primary input and mentions optional preferences indirectly, but adds no new semantic 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 clearly states this tool maps an occupation (by SOC code) to destination occupations and associated roads/bridges/demand. It goes beyond a tautology, but relies on unexplained domain jargon like 'typed roads' and 'karat', and does not explicitly distinguish itself from the closely named sibling find_pathways.

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 opening question 'Where can this occupation lead?' implies when the tool is appropriate, and 'For a SOC code' gives a concrete input condition. However, it does not name alternatives or give exclusion criteria, so an agent must infer when to prefer this over siblings like find_pathways or compare_destinations.

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 only readOnlyHint=true, the description adds meaningful details about what is returned (parties, pathways, bundles, checklists, version/source counts) and what is excluded (signatories as people). However, it doesn't clarify pagination, size limits, or authentication needs. The added return-shape context is valuable but incomplete.

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 verbose and buried in dense, clause-heavy sentences. The core purpose is stated first but then followed by multiple paragraphs of edge-case metadata explanations. It is not front-loaded for quick scanning; an agent must parse several complex conditions.

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 attempts to cover return content and edge cases, which is helpful given no output schema. However, it omits basic operational details like response size, pagination, or how to handle missing entities. For a read tool with one parameter and no output schema, it is adequate but not 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% and there's only one parameter (agreement_id). The description adds no parameter-specific syntax or constraints beyond what the schema says. Baseline 3 is appropriate when the schema fully documents the parameter.

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 a single agreement with its related entities (parties, pathways, comparability bundles, checklists). It is distinguishable from siblings like find_agreements (list) and get_institution (different resource), though the phrasing is somewhat tangled with extended metadata caveats.

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 you need an agreement_id from find_agreements, but it doesn't explicitly state when to use this versus find_agreements or get_program. The mention that 'forms themselves come from the one-record get, never from a list' hints at a usage rule but is not framed as 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 only supply readOnlyHint=true, leaving the description to carry the behavioral burden, and it does disclose real detail: which fields belong to the current form's source, that version_count/source_count/first_edition_seen/last_edition_seen appear only for records with multiple forms or sources, and that the Union retains records absent from any current catalog. This is substantive context beyond what the annotation provides, though it is expressed obliquely.

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 dense, meandering block of very long sentences with no clear front-loaded summary of what the tool does. Field-level conditional behavior is packed into prose that an agent must parse carefully, and key information (the actual purpose) is buried behind return-value detail.

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 must describe the return value, and it does cover the row's shape, the conditional multi-form/multi-source fields, and the stale-edition note. However, the coverage is cryptic and omits basics such as the response wrapper or how the institution-sharing data is structured, leaving meaningful gaps for a read 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% with a single documented parameter ('A catalog id from find_catalogs'), so the schema already does the heavy lifting. The description adds no syntax, format, or sourcing detail beyond what the schema supplies, so the baseline of 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 opens with 'One catalog edition' and enumerates what the returned row contains, so the resource is identifiable, but it never states a clean verb like 'retrieve a single catalog by id' and never explicitly distinguishes itself from the sibling find_catalogs. An agent can infer it is the single-record getter, but mostly from the sibling name rather than the description.

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?

There is no indication of when to use this tool versus find_catalogs, nor any prerequisite beyond the schema's 'catalog id from find_catalogs'. The line 'the forms themselves ... come from the one-record get' gestures at another tool but is cryptic and doesn't establish a selection rule.

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 readOnlyHint annotation already signals a safe read operation dropped the 'grant' clause' — wait, no annotation contradiction. The description adds useful behavioral detail by enumerating the categories of data returned and noting 'where held' (Credential Engine registry identity). It does not disclose error behavior or response shape, but for a read-only fetch this is reasonably transparent.

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 long sentence, but every clause enumerates a distinct data facet. It is descriptive without padding, although it front-loads the purpose before listing contents. Slightly dense but well organized.

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 one clearly-documented parameter and readOnlyHint annotation, the description sufficiently specifies what data is returned. It does not mention error handling or what happens if the id is invalid, but those are typically not expected in tool descriptions. Overall, adequate for a simple look-up 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?

The input schema provides a full description of the id parameter ('A certification id, copied from a search result's id field'), so schema coverage is 100%. The tool description adds no additional parameter semantics beyond implying the id identifies a single certification. 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 uses a specific verb phrase ('Everything held about one certification') and enumerates the exact data categories returned, distinguishing it from list/search tools like search_certifications or relationship tools like certifications_for_occupation. It is immediately clear this is a single-record fetch by id.

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 it is for retrieving a complete certification record by id, but it never explicitly states when to choose it over siblings like search_certifications or related_certifications. No exclusion or alternative guidance is provided, relying on the tool name and schema (id parameter) to convey usage.

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 only declare readOnlyHint, so the description carries most of the burden and does so well: it discloses pagination (items come in pages, answer states items_total and next_item_offset), conditional field presence (version_count/source_count/first_edition_seen/last_edition_seen only for multi-form or multi-source records), and provenance/edition caveats. These are genuine behavioral traits beyond what the single annotation provides.

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 opening question 'What does this award require?' is a strong front-loaded hook, but the body is a dense, jargon-heavy run-on about sources, forms, and the Union. Content is largely relevant, yet it is not economical and reads as overly repetitive in places.

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 must explain the return shape and does so extensively: requirement groups with headers and item counts, items with credits and alternatives, per-row provenance and conditional version/source fields, pagination totals. This is close to complete, though the routing/comparison case for this tool versus siblings remains unsaid.

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 all three parameters are already documented, including item_limit defaults/caps and checklist_id sourcing. The description implies pagination flow (next_item_offset) but adds no syntax or format detail beyond the schema, so the 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 states a specific verb+resource: retrieve one checklist's requirement groups, items, published credit strings, alternatives, and resolved course code/title/credits. An agent can distinguish it from list-oriented siblings like find_checklists and compare_program_checklists. It never explicitly names those siblings, but the singular 'one checklist' scope is clear.

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?

There is no explicit when-to-use guidance relative to siblings (find_checklists, compare_program_checklists, get_program). The only routing hint is negative: forms 'come from the one-record get, never from a list,' which does not tell the agent when to pick this tool over alternatives.

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 only declare readOnlyHint=true, so the description carries most of the behavioral load and does add real value: it discloses conditional output (version_count, source_count, first_edition_seen, last_edition_seen appear only for multi-form/multi-source records), that single-form records 'read exactly as they always has', and that stale older-edition records are retained. It stops short of stating auth needs or pagination 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 middle sentences earn their place by explaining conditional fields and source scoping, but the prose is convoluted and contains flourishes that hurt rather than aid parsing ('one sentence saying so in words', 'reads exactly as it always has'). It is not front-loaded with the most decision-relevant 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?

There is no output schema, so the description must describe the return shape and largely does so, covering the bundle's parts, per-row source attribution, and the conditional field set. That is a substantial compensating effort for a tool with no output schema, though a few field meanings remain vague.

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?

One parameter with 100% schema description coverage, so the schema already documents the comparability_id fully; the description adds only the implicit provenance (find_comparability). Baseline 3 is appropriate when the schema does the work.

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 ('One comparability bundle') and enumerates what the bundle contains: its row, the receiving institution, and its source and substitute courses. It also explicitly differentiates from list-shaped siblings ('The forms themselves ... come from the one-record get, never from a list'). The dense, idiosyncratic phrasing slightly obscures the core purpose but the resource is identifiable.

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 schema-plus-description pairing implies the id comes from find_comparability, and the description draws a boundary against list tools. However, there is no explicit when-to-use/when-not statement and no named alternative beyond the implicit reference to 'the one-record get', so usage is only implied.

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, so safety is covered. Beyond that, the description adds real behavioral context: the summary is read 'as published and never computed', unpublished data 'is said so', and a record's fields reflect only its current FORM's one source, not the record's whole span. These are substantive disclosure beyond the annotation.

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 dense, run-on block that mixes the tool's purpose with row-shape trivia, field-level rules, and a note about a sibling tool. It is poorly front-loaded past the opening question and contains many clauses that do not help an agent decide to call this tool. Verbosity actively hinders comprehension.

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 and no parameters, the description carries the full burden of describing what is returned, and it does name the returned elements (per-area counts, row counts, sector breakdowns, census verdicts, per-state counts) and the conditional row fields. It is wordy but substantively complete for a parameterless read 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?

The tool takes zero parameters, so the baseline is 4 and the description cannot add parameter detail. Nothing here detracts; no parameter semantics are 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 opening question 'What does CourseShelf hold?' and the enumeration of counts (institutions loaded, row counts, organizations by sector, census verdicts) do convey that this is a read-only summary of published build records. However, the bulk of the text describes row-level metadata (source_url, version_count, first_edition_seen) rather than the tool's purpose, and nothing distinguishes it from sibling get_dictionary_summary. The core purpose is inferable but heavily obscured.

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?

There is an implicit routing hint: 'The forms themselves... come from the one-record get, never from a list', which steers the agent to a different tool for detailed forms. But there is no explicit statement of when to call this summary versus alternatives, and no stated prerequisites or exclusions. Guidance is implied rather than declared.

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, but the description adds meaningful behavioral detail: data is read as published at boot, never computed at request time, and not-held items are reported honestly. It does not contradict annotations and provides useful context beyond 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 somewhat ornate but every clause carries distinct information: content layers, versioning, boot-time behavior, and the explicit word-lookup exclusion. It is not bloated, though it could be tightened without losing meaning.

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 zero-parameter read-only summary tool, the description is complete. It states what is included, how freshness works, what not-held means, and what the tool is not for. No output schema exists, so return-value explanation is not required.

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 tool has zero parameters and the input schema is empty, so parameter semantics are trivial. The description fully compensates for any potential ambiguity by describing what the tool returns even though no parameters require explanation.

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 summarizes what the KSA Dictionary holds, enumerating specific content types and explicitly distinguishing it from resolve_term for word lookups. This goes beyond the title and differentiates it from 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?

It explicitly gives a when-not-to-use rule ('never a word lookup') and routes to the correct sibling ('for one word use resolve_term'). It also clarifies that the summary reflects boot-time state, which informs the caller's 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?

With only readOnlyHint=true declared, the description carries real behavioral weight: it discloses that contacts are 'not served', that per-row source fields describe only one source, that multi-form/multi-source records gain version_count/source_count/first_edition_seen, and that stale records from older editions still appear. These are genuine traits beyond the annotations, though some are return-value detail rather than 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 a dense, comma-chained paragraph that mixes payload inventory, edge-case rules and editorial notes without structure or headings. The core purpose is front-loaded but quickly drowned; significant trimming would improve usability.

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 single-record get with no output schema, the description usefully documents the shape of the returned composite (identity, identifiers, addresses, costs, calendars, counts). It compensates for the missing output schema, though organization is poor and a few clauses are cryptic.

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 both alternative identifiers (organization_id from find_institution, or unitid). The description adds no parameter-level guidance, so the 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 makes clear this is a whole-record read for a single institution ('Everything held about one institution: its identity row, identifiers, addresses, websites...') and explicitly distinguishes itself from list tools ('come from the one-record get, never from a list'). The specific verb is weak and buried under payload detail, but the resource and scope are 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?

There is no explicit statement of when to prefer this over find_institution or programs_for_institution. The only routing signal is indirect ('the one-record get, never from a list'), and the id source is left to the schema's 'from find_institution' note. Usage is implied rather than stated.

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 only declare readOnlyHint=true, and the description goes well beyond that: it discloses conditional return fields (version_count, source_count, first_edition_seen, last_edition_seen appear only for multi-form/multi-source records), per-row source attribution, and that records from older editions are flagged. This is meaningful behavioral context, though phrased opaquely.

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 wall of long, comma-spliced sentences with the core purpose buried after tangents about version counts and edition stamps. Key information is not front-loaded, and several sentences restate the same conditional-field idea in prose and field names.

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 describing the return shape, and it does so thoroughly — enumerating returned sections, conditional fields, and per-row provenance. It is dense but covers the complexity of a rich single-record fetch adequately.

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 origin ('from learning_units or get_checklist') is documented in the schema, so the description owes little here. It adds no format or syntax detail beyond the schema, so the baseline of 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 states a specific resource and enumerates its parts (row, prerequisites, aliases, terms, articulation statements, transfer frameworks), so an agent knows this retrieves one fully-assembled learning unit. It implicitly distinguishes itself from list tools ('come from the one-record get, never from a list') but never names a sibling tool directly.

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?

There is implicit routing guidance ('The forms themselves ... come from the one-record get, never from a list'), which hints at the list-vs-get distinction. However, it never states when an agent should call this versus learning_units, get_checklist, or compare tools, so usage is only inferable.

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 only readOnlyHint as annotation, the description carries the return contract in detail: conditional fields such as version_count and source_count, source-level versus record-level provenance, contacts as names only, and behavior for records last seen in older editions. This goes well beyond the read-only annotation and does not contradict it.

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 dense, sprawling block with multiple run-on sentences and awkward phrasing. The useful return-shape details are not front-loaded or organized, making it difficult to parse quickly, even though much of the content is relevant.

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?

There is no output schema, so the description must explain return values and it does so extensively, covering conditional fields, provenance rules, and older-edition behavior. It is nearly complete for a read-only single-record get, though it could be clearer and does not address error or auth cases.

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 pathway_id is already fully documented in the schema as coming from find_pathways. The description does not add syntax, format, or validation detail beyond what the schema provides, so the 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 first sentence identifies the resource and its linked entities: one pathway, its row, and the checklist and agreement it links. It also distinguishes this from list-oriented tools by saying forms come from the one-record get, not from a list, though it does not name find_pathways as the discovery alternative.

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: call this when you have a pathway id and need the single pathway record. The description hints that forms must come from the one-record get rather than a list, but it does not explicitly state when to use this tool versus find_pathways or get_agreement/get_checklist.

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?

Beyond readOnlyHint=true, the description discloses conditional return behavior: version_count, source_count, first_edition_seen and last_edition_seen appear only when a record holds multiple forms/sources, and older-edition records are flagged. This is genuine behavioral context the annotations do not cover, though it never clarifies what a 'form' or the 'Union' actually are.

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 core purpose is front-loaded, but the remaining text is dense, jargon-heavy and hard to parse ('never the record's whole span', 'reads exactly as it always has'), and spends sentences on backwards-compatibility meta-commentary that adds little for an agent. It is over-long for a one-parameter read tool.

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?

There is no output schema, so the description must carry return-value meaning, and it does describe fields and conditional presence. However, key terms ('form', 'Union', 'source') are never defined, leaving an agent without a clear mental model of what is actually returned.

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?

With a single parameter and 100% schema description coverage, the schema already documents policy_id as 'A policy id from find_policies.' The description adds nothing further about the parameter, so the baseline of 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 opening sentence gives a specific verb and resource with the returned fields (section, verbatim text, page, edition, source) and distinguishes itself from list tools ('come from the one-record get, never from a list'). It is clear this retrieves a single policy, though the sibling differentiation is partial rather than explicit.

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 only implied: the schema ties policy_id to find_policies, and the description notes forms 'come from the one-record get, never from a list.' There is no explicit statement of when to call this versus find_policies or get_catalog, so the guidance remains inferential.

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?

Beyond the readOnlyHint annotation, it discloses meaningful conditional behavior: version_count, source_count, first_edition_seen and last_edition_seen appear only when a record has more than one form or source, and a record with one form/source omits them. It also notes older-edition retention via the Union. Return-shape behavior is described without an output schema, adding real value.

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 main purpose is front-loaded, which is good, but the prose is dense and cryptic, with run-on sentences and awkward phrasing ('a record with one form and one source carries none of them and reads exactly as it always has'). Several clauses are hard to parse on first read.

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 the return shape and does so, including conditional fields and provenance semantics (source_url, capture_file, catalog_year belong to one form's source, not the whole record). It is adequate, though the obtuse style leaves some room for misinterpretation.

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 program_id parameter is fully documented in-schema (with an example and a pointer to programs_for_institution / find_programs). The description adds nothing about the parameter, so the baseline of 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 names a specific verb+resource ('One program whole') and enumerates what it returns: its row, identifiers, offerings, institution, and checklists. It also distinguishes itself from list siblings ('The forms themselves... come from the one-record get, never from a list'). The dense phrasing muddies an otherwise clear 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?

It implies a routing relationship ('pass one to get_checklist') and states that full form content comes from the single-record get rather than a list. However, it never explicitly says when to choose this over find_programs or programs_for_institution, so context is only inferable.

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 only readOnlyHint=true in annotations, the description carries the full burden and does so extensively. It discloses conditional output fields (version_count, source_count, first_edition_seen, last_edition_seen), explains when they appear, and clarifies that forms and sources are returned here rather than in a list.

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 first sentence is front-loaded and clear, but the remaining text is dense, jargon-heavy, and wordier than necessary. The conditional-field details are useful, though they could be compressed and structured more cleanly.

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?

There is no output schema, so the description must explain return values, and it does so thoroughly: core fields, conditional fields, source attribution, and older-edition behavior are all covered. It still lacks some operational context such as error behavior, but for a read-only one-record get it is largely 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 the single framework_id parameter is already documented in the schema as coming from find_transfer_frameworks. The prose adds no extra parameter syntax, constraints, or formatting guidance beyond that baseline.

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 identifies a single transfer framework and lists what it returns (row, authority, codes, mapped courses), which is specific enough to separate it from list-style siblings. However, it relies on the name/title for the action verb and does not explicitly name find_transfer_frameworks as the companion 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?

Usage is only implied: the parameter description says the id comes from find_transfer_frameworks, and the prose says forms come from the one-record get, never a list. There is no explicit when-to-use guidance or when-not-to-use alternative comparison.

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 establish readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful shape information beyond that: conditional fields (version_count, source_count, first/last_edition_seen appear only for multi-form or multi-source records), verbatim credit strings where ranges stay ranges, and the fact that a record can survive without any current catalog printing it. Pagination behavior and ordering are not disclosed.

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 purpose is front-loaded, but the remainder is a dense run-on chain of clauses mixing filter behavior and return-shape trivia ('reads exactly as it always has', 'the Union keeps a record no current catalog prints'). Several sentences describe output detail in prose that is harder to parse than the structured fields would be, and the text is far longer than the tool's filter behavior warrants.

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 must carry the return-shape burden, and it does describe row fields (source_url, capture_file, catalog_year, version_count, edition spans) and their conditional presence. However it omits ordering, total counts, and how offset/next_offset round-trips, leaving gaps for a paginated list 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%, so baseline is 3, but the description adds real meaning beyond the schema: it tells the agent that course-code matching ignores spaces and case, which the schema does not say, and names the subject/code/title filter axes. It does not clarify unit_type or offset/linkage to the prior answer beyond what the schema states.

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 opening states a specific resource and action ('what courses does this institution publish') and lists the filter axes, so an agent knows this is a filtered course listing. It also explicitly distinguishes itself from the single-record get ('the forms themselves ... come from the one-record get, never from a list'), which is valuable sibling differentiation. It does not, however, differentiate itself from search_programs_and_learning_units, the closest-looking sibling.

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 filter list and by the exclusion of the detail get, but the description never states when to prefer this over search_programs_and_learning_units or when a unitid-only browse is appropriate. The 'use the get for forms' note is a partial when-not, not a full routing rule.

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 annotations already declare readOnlyHint=true, so the safety profile is known. The description adds a little context by defining the result as issuing organizations and noting the optional name filter, but it does not disclose pagination behavior, output shape, or rate limits; with the read-only annotation, a 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?

The description is a single concise phrase with the core resource and optional filter front-loaded, and there is no filler. It loses one point for being a sentence fragment rather than a complete instructional phrase.

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-only list with no required parameters and full schema coverage, the description is nearly sufficient. The main gap is that without an output schema, it does not state the return shape or pagination behavior, which an agent would need to interpret the response confidently.

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 all parameters (limit, query, offset) are documented in the input schema. The description's phrase 'filtered by a name query' mirrors the query parameter without adding meaning beyond what the schema already 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 identifies the resource ('issuing organizations') and the optional name-query filter, which clearly maps to the list_issuers operation. It stops short of a full verb phrase like 'Lists the issuing organizations,' and it does not explicitly distinguish itself from sibling tools, though no sibling targets issuers.

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?

There is no guidance on when to use list_issuers versus alternatives such as search_certifications or related_certifications. The only hint is the optional name-query filter, which describes parameter behavior rather than decision 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?

Beyond the readOnlyHint annotation, the description discloses that no data is stored, that the package is returned intact, and that learner_decisions are honored. It also explicitly states it is never a grade or credit decision, adding behavioral context beyond 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 three sentences, each contributing distinct value: content definition, purpose/non-grading, and persistence/honoring decisions. It is front-loaded with the core function and avoids 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 the output schema exists and annotations cover read-only, the description covers purpose, behavior, storage, and decision honoring. It omits explicit parameter details for language, but that is a minor gap given the schema and optionality. Overall, it is complete for an agent to call it 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 67%, with package and aspiration described in the schema. The description reinforces the role of the package (kept and returned) but adds no new parameter semantics. The language parameter lacks a schema description and the tool description does not compensate, leaving it ambiguous. 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 verb and resource: it shows the person's Selfie from their evidence package, enumerating the seven dimensions and their sources. It also clarifies it is a mirror for confirmation, not a grade or credit decision, distinguishing it from any decision-making 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 provides clear context: it is for the person to confirm, refine, or reject their Selfie, implying a review use case. However, it does not explicitly state when not to use it or name alternative tools, though its unique role among siblings makes this less critical.

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?

readOnlyHint=true already covers the safety profile, and the description is consistent with it. However, the description adds no behavioral context beyond the query semantics—no mention of pagination, ordering, or what the result contains—so it does not go beyond the 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 a single short question with no filler and the essential relationship is front-loaded. It is appropriately sized for a simple lookup tool.

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 low-complexity read-only lookup, the description plus the fully documented schema is nearly sufficient. Since there is no output schema, stating the return shape or pagination behavior would add value, but limit/offset are already documented and the question implies a list of occupations.

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 descriptions and examples for id, limit, and offset. The description adds no parameter-level information beyond what the schema already documents, so it receives the baseline score of 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 identifies the resource (a certification) and the requested result (the occupations it serves), so an agent can infer the direction of the query. It is not phrased as an imperative like 'list' or 'return', and it does not explicitly contrast with the inverse sibling certifications_for_occupation, which keeps it from a 5.

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 no guidance about when to use this tool versus the closely related siblings such as certifications_for_occupation or related_certifications. It only restates the purpose, leaving the agent to infer selection criteria from tool names.

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 only readOnlyHint available in annotations, the description adds substantial output behavior: source attribution per form, conditional version_count/source_count, older-edition notes, and the fact that forms are not returned by this list. This goes well beyond the annotation and usefully discloses representation quirks.

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?

It front-loads its purpose but then becomes a dense, run-on paragraph of output-field rules. The detail is useful given there is no output schema, yet the structure is not scannable and several clauses are heavily nested.

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 list tool with no output schema and full schema parameter coverage, the description is complete about return shape and edge cases. It leaves tool-selection guidance thin, but the output context is rich enough to call the tool 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?

All four parameters are documented in the schema with 100% description coverage, so the baseline is 3. The description adds no additional parameter syntax or constraints beyond referencing the institution and the checklist-id handoff.

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 opening question names the resource (programs) and scope (for this institution), so the agent knows it is a read/list operation. It does not explicitly compare itself to siblings like find_programs, but the purpose is clear without sibling differentiation.

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 mentions downstream use of checklist ids with get_checklist and warns that forms themselves come from the one-record get, never from a list. However, it gives no guidance for choosing this tool over find_programs or search_programs_and_learning_units, so usage is implied rather than explicit.

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 only provide readOnlyHint=true, so the description carries the burden of behavioral disclosure. It adds a meaningful semantic constraint: traversal happens on SOC only and CIP-only matches are excluded. This goes beyond the structured fields and does not contradict the 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 short sentences front-load the user-facing use case before the technical qualifier. Every clause contributes: the question, the traversal rule, and the CIP exclusion. There is no redundant or filler content.

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 tool with one required parameter, the definition covers core semantics and the schema documents pagination. However, since there is no output schema, it would be marginally stronger to explicitly state the result shape (e.g., a list of related certification records), so it is not a 5.

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%, with id, limit, and offset each documented including defaults and source guidance (e.g., 'copied from a search result's id field'). The description adds no parameter-specific detail, so the baseline score 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 frames the tool with a clear question ('What else serves the same occupation?') and a specific verb ('Traverses on SOC only'). It explicitly contrasts with CIP-only relations, which distinguishes it from sibling tools like certifications_for_program.

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 opening question identifies the use case: when holding a certification, find other certifications serving the same occupation. It also states a firm exclusion (a certification sharing only an instructional program is not related), giving an explicit criterion for what will not be returned. It does not name alternate tools, but the usage context is 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?

With readOnlyHint=true already covering the safety profile, the description goes further and discloses the return structure: three linked layers (governed lexicon, O*NET, WordNet index), per-layer attribution with provenance, and that the WordNet placement carries a gloss and synonyms. That is genuinely useful output-context that the annotations do not provide, though it says nothing about lookup failures or ambiguous-term handling.

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 opening question is a strong front-loaded hook and the rest is one dense but purposeful paragraph. Some phrasing ('so both sides resolve to the same identifiers, never spelling matches') is wordy, but each clause contributes semantic or output information rather than padding.

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 single-parameter, read-only lookup with no output schema, the description supplies the missing return-shape information (layers, provenance, gloss, synonyms) and the conceptual purpose. It is nearly complete; only edge-case behavior (no match, ambiguity) is left unstated.

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 the single 'term' parameter, including examples, so the schema already carries the parameter burden. The description adds only conceptual framing (a word for what a learner knows/does) and no syntax, format, or matching-rule detail beyond the schema, so the 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 states a specific verb and resource — placing a word within the KSA model / dictionary — and explains the semantic-resolution mechanic (shared identifiers, not spelling matches). It is clear what the tool returns, though it never explicitly differentiates itself from the related sibling expand_term, so an agent must infer the boundary.

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 opening question ('Where does a word place in the KSA model?') and by the vocabulary-resolution framing, but there is no explicit when-to-use, no when-not-to-use, and no named alternative such as expand_term or crosswalk_code. The agent gets context but must infer the routing decision.

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?

readOnlyHint=true already covers safety, so the description's added value is the disclosure that it returns multiple candidates rather than one guess when ambiguous, plus what each candidate contains (ids, issuers, source basis). This is meaningful behavioral context beyond the annotation.

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?

Front-loads the central question and keeps to a few tight sentences. There is minor redundancy in restating the 'trade, field, job, company' list that also appears in the schema examples, but overall it is well-structured.

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?

An output schema exists so return values needn't be re-explained, and the description still usefully previews candidate shape and the id hand-off to other tools. Adequate for a 4-param search/resolution 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 all four parameters (including limit default/max, issuer, offset) are already documented in the schema. The description's 'everyday words' framing reinforces the query parameter but 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?

Frames the tool as a name-resolution step ('Which certification is this prose name?'), which cleanly distinguishes it from get_certification (lookup by id) and by-occupation siblings. It states the resource and the operation, though it doesn't name a specific sibling to avoid.

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 to 'start here for any plain question' and enumerates the everyday-word inputs it accepts, and notes the returned ids 'feed the other certification tools.' That routes the agent well, but there is no explicit when-not or negative case.

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 readOnlyHint=true already covering the safety profile, the description still adds substantive behavioral context: how records with multiple forms/sources carry version_count, source_count, first/last_edition_seen, and that records from older editions are flagged. That is genuine disclosure beyond the annotation, though it says nothing about result size limits or pagination behavior beyond offset.

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 prose is a single sprawling block of convoluted clauses, and the bulk of its length is spent on result-shape details (version_count, edition flags) rather than front-loading the core purpose. It is not under-specified, but it is poorly structured and repetitive about the single-form/single-source case.

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?

An output schema exists, so explaining return values was not strictly required, yet the description spends most of its length doing exactly that. For a 15-parameter, high-complexity search the description leaves several filters (credential, subject_code, code, sector) to the schema alone, so it is adequate but not 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 the schema already documents all 15 parameters and the baseline is 3. The description restates query/place/award semantics that mostly duplicate the schema, adding little new syntax or format meaning beyond the 'words of 3+ characters' rule.

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 opening 'Which programs or courses match, and where?' states a specific retrieval verb over a named resource and enumerates the inputs that drive matching. It is clear what the tool does, though sibling differentiation from find_programs / learning_units / programs_for_institution is only partly addressed (it only explicitly routes the per-form detail to 'the one-record get').

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?

There are real usage constraints ('Courses across every school need words of 3 or more characters; words held by very many courses need a state, city or school') and a routing hint to the get tool for forms. But there is no explicit statement of when to prefer this over find_programs or learning_units, so guidance is implied rather than stated.

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?

Beyond the readOnlyHint annotation, it discloses that nothing is stored, that the tool is a non-committal case for prior learning review (say may, never will), and that unmatched learning becomes block credit. These are exactly the behavioral caveats an agent needs and there is no contradiction with the annotation.

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 every clause carries operational content: program lookup, line-by-line output, block-credit fallback, epistemic caveat, and statelessness. The first sentence is slightly rhetorical and could be tightened, but overall it is structured and front-loads the core behavior.

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 rich input/output schemas and readOnlyHint, the description covers the main branches and output semantics well. It does not need to explain return values because an output schema exists, and the description resolves the important caveats such as storage and wording.

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 already describes 4 of 5 parameters, so the description adds value by specifying that package must be returned whole, that checklist_id defines the only courses considered, and that without it no course suggestion occurs. target_unitid is also clear from 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 clear resource and action: map a person's learning claims to a specific program checklist and suggest credit line by line, including which claims are supported, covered by transfer, or still needed. It references find_programs for obtaining checklist_id, which helps situate it among siblings, though it does not explicitly contrast it with alternatives.

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 practical setup context: use a GoldRibbon package and name the target program with checklist_id from find_programs. It also explains the no-program fallback, but it does not state when to prefer this tool over siblings such as will_my_credits_transfer or draft_my_claims.

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 annotations only providing readOnlyHint, the description adds rich behavioral context: the three-state output semantics (covered/missing/unknown), the guarantee that 'unknown' is never a guess, the caveat that this is 'a case to argue, not a verdict,' and detailed source attribution rules. It also explains version and source counts for multi-form records and the behavior for records last seen in older editions. This goes well beyond what the annotation conveys.

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 the core question, but it then becomes a long, dense block that explains output states and source attribution in detail. Because an output schema exists, much of the return-value explanation is redundant and could be trimmed. The text is not wasteful enough to score 1 or 2, but it is far from concise.

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 domain complexity and the presence of an output schema and readOnly annotation, the description supplies all the context an agent needs: what is evaluated, what the states mean, how sources are attributed, and the important caveat that recognition is the school's act. It covers edge cases like multi-form records and older editions that a caller would otherwise have to discover. The definition is complete for correct 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?

Schema description coverage is 100%, so the input schema already documents the held array, checklist_id, and target_unitid thoroughly. The description reinforces the kinds of held items (AP, CLEP, IB exams, courses) and the target school, but adds little syntax or format meaning beyond the schema. The baseline of 3 is appropriate when the schema does the heavy lifting.

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 question and resource: whether prior credits (AP/CLEP/IB exams or courses) apply as credit at a target school. It is highly specific about the evaluation's three states and output fields. It does not explicitly differentiate itself from sibling tools, but the purpose is clear enough to distinguish it from general lookup 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 implies usage by explaining what the tool answers and when each state occurs, but it never states when to use this tool versus alternatives such as find_agreements or compare_destinations. There is a note that forms come from the one-record get, never from a list, which is a retrieval instruction but not an explicit usage guideline. Guidance is implied rather than stated.

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