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?

Beyond the readOnlyHint annotation, the description discloses a meaningful data-integrity behavior: unresolved requirement items are 'never guessed into this list,' which tells the agent results are conservatively filtered rather than exhaustive. It also outlines the item shape returned, adding value the annotation does 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?

Three short sentences, front-loaded with the core question, then the returned fields, then the accuracy caveat. No filler or repetition — every sentence carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully characterizes the return payload (checklist id, award, group heading) and the resolution semantics, which is what an agent needs to interpret the answer. It stops short of describing pagination behavior, though limit/offset are self-documented in the 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 limit, offset, and learning_unit_id, including the example id and where to obtain it. The description adds no syntax, format, or defaulting detail for the parameters, 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 precise reverse-lookup purpose ('Which checklists require this course?') and enumerates what each returned item contains (checklist id, award, group heading). It is clearly distinguishable in direction from siblings like find_checklists and get_checklist, though it never names them explicitly.

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 natural-language framing of the question, and the parameter description points the agent at learning_units/get_learning_unit as the source of the id. However there is no explicit when-to-use/when-not statement and no named alternative for adjacent needs such as browsing checklists.

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 behavioral burden and delivers materially: it discloses that held rules are consulted before live rules, that each rule carries source authority, source_url, and band, that results are comparable rather than equivalent, and that incoming 'lands on' rules come only from held data. This is valuable non-obvious behavior beyond the read-only flag.

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 only two sentences, front-loaded with the core question and free of filler. It loses one point because it packs in domain-specific terms like CourseShelf, CourseAtlas, and band without definitions, making the second sentence dense and slightly harder to parse.

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 nine parameters, none required, and no output schema, the description should clarify the identifier contract: the tool is explicitly 'for one course,' yet it never says that code, title, or learning_unit_id must identify that course (with school/unitid as disambiguators). It also leaves list/pagination behavior mostly to the limit/offset schema hints. The rule-shape detail partially compensates, but the missing selection contract is a real 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?

The schema already documents 100% of the parameters, including direction semantics and the optional school/unitid disambiguators, so the baseline is 3. The description reinforces the lands_as/lands_on distinction and the 'one course' idea but does not add parameter-specific meaning beyond what the input 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 opens with a precise framing of the operation: where a course lands at other schools and what lands on it, for a single course. It explicitly identifies the domain as published transfer rules and adds a key semantic distinction, 'comparable, never equivalent,' which separates it from generic equivalence or transfer-credit tools. This is specific enough to distinguish it from sibling search, compare, and credit-transfer 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 gives clear context: this tool is for one course's comparability and covers both directions by default, with a well-defined data precedence ('rules CourseShelf holds first ... then CourseAtlas's direct rules read live'). It does not explicitly name alternatives or state when-not-to-use, so it falls just short of full routing 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 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?

With only readOnlyHint=true in annotations, the description adds real behavioral context: 'Nothing is summed or computed by the service,' 'Schedule is stated not held,' and that absent institutions/checklists/costs are explicitly stated as missing rather than omitted. These clarify gap handling beyond the annotation, though return format and paging semantics are only implied.

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?

Dense but purposeful — the comparison target is front-loaded, then the work-effort/cost distinction, then the no-computation and gap-statement guarantees. Mildly run-on phrasing costs it a point rather than any wasted sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-shape burden and does so: requirement groups, items, credit strings, and the tuition/fee policy are enumerated. It is usable as-is, though a concrete note on how the paired cost and checklist are keyed would make it fully self-contained.

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 unitids, program, detail, and institution_offset are already documented, including the 5-per-call batching. The description reinforces the per-UNITID semantics but adds no syntax or format detail beyond what the schema provides, so the baseline 3 holds.

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 (a program's published checklists across several institutions), plus the paired cost dimension, so the agent can tell it apart from single-record siblings like get_checklist or find_checklists. It stops short of naming a sibling explicitly, which is what would push this to 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 multi-institution framing implies the use case (comparing one program across UNITIDs) but no sentence states when to prefer this over find_checklists/get_checklist or what to do when a single institution is wanted. Usage is left to inference.

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 already declare readOnlyHint=true, so the safe-read profile is covered. The description adds one genuine behavioral fact beyond that — an empty result set is reported as 'none held' rather than an error — but says nothing about pagination behavior even though offset/next_offset semantics exist, leaving that to 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?

Three short sentences, front-loaded with the core question the tool answers, with no redundant boilerplate. The phrasing of the final clause ('Answers none held when the build holds none') is slightly awkward but still compact and information-dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero required parameters, full schema coverage, and no output schema obliging the description to explain return values, the definition covers both filter dimensions and the empty-result behavior. Only the missing routing against get_agreement/find_transfer_frameworks keeps it from being fully 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 four parameters (limit, query, offset, unitid) are already documented in the schema. The description restates query and unitid but adds no syntax, format, or default detail beyond what the schema provides, 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: looking up which articulation or transfer agreements are held, and describes the two filter axes (title words or a party UNITID). However, it does not distinguish itself from the near-name siblings get_agreement or find_transfer_frameworks, which an agent could easily confuse with it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It signals the intended search modes ('optional title words, or an institution's UNITID as a party'), which implies the tool is a filtered lookup rather than a by-ID fetch. But it never states when to use this instead of get_agreement (single lookup) or find_transfer_frameworks, so routing between the two find-tools is left to inference.

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 the safety profile is covered. The description adds the useful edge-case behavior that it answers 'none held when the build holds none' and lists the returned fields, but says nothing about pagination limits or how limit/offset interact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the core question and followed by the return fields and an edge case. Efficient, with only minor awkwardness in the final clause.

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 with fully documented parameters and no output schema, the description covers what is fetched and what is returned, including the empty-result case. It is nearly complete, needing only brief routing guidance versus the singular sibling.

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 fully documents unitid, limit, and offset. The description adds no parameter meaning beyond that, which is the expected baseline 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: which published catalog editions are held for an institution, and names the returned fields (edition year, format, source). It is clearly distinguishable in spirit from the singular get_catalog, though it never names that sibling explicitly to draw the contrast.

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 such as get_catalog or find_programs, nor any stated prerequisites. Usage is only implied by the resource being queried.

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 the read-only safety profile is covered structurally. The description adds useful domain semantics about what a checklist represents but says nothing about result volume, ordering, or how pagination behaves in practice, so it adds only modest behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The primary question is front-loaded in the first sentence and the filtering guidance follows immediately. It is compact and wastes little, though the em-dash apposition makes the opening sentence slightly heavier than it needs to be.

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 a fully documented 5-param schema and no output schema, the description supplies the essential domain framing and sibling routing. Missing are expectations about result shape and pagination flow, which are largely implied by the schema's offset/limit fields.

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 limit, offset, unitid, query and program_id are all documented in the schema. The description confirms that query/program_id act as narrowing filters but adds no syntax, format, or interaction detail beyond that, making the baseline 3 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 resource (checklists published by an institution) and even defines the domain term — 'the generic itinerary of requirements for an award' — which removes ambiguity an agent could not resolve from the name alone. It is clearly distinct from the singular sibling get_checklist.

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 explains that award words or a program id narrow the result set and explicitly routes to get_checklist when one checklist is wanted. It does not state when this tool should not be used (e.g. versus compare_program_checklists or checklists_requiring_learning_unit), so it falls short of full routing 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?

The annotations already provide readOnlyHint, and the description adds a useful behavioral edge case: 'Answers nothing when the build holds none.' It does not describe the shape of results or pagination, but it adds some value 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 succinct and front-loads the core purpose in the first sentence. The second sentence adds a useful boundary condition. The misleading 'curriculum language' phrase costs it a top score.

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 not fully define the result shape beyond 'which comparability bundles are held,' and the confusing filter reference leaves the agent unsure about valid parameters. It is adequate for a basic read-only list/find tool but not complete enough for effective tool selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage, so a baseline of 3 is expected, but the description introduces 'curriculum language,' which is not a schema property, instead of faithfully representing the agreement filter. It also leaves unclear whether the optional filters are exclusive or combinable, which creates ambiguity for agent invocation.

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 as comparability bundles and the operation as finding which ones are held, even including the edge case of returning none. It is unambiguous about the subject, though it does not explicitly contrast itself with siblings like 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?

The description offers optional filtering hints, but no guidance on when to use this tool versus alternatives such as get_comparability or will_my_credits_transfer. There is no 'when to use' or 'when not to use' framing, leaving tool selection to inference.

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 disclose the response content (identity, sector, identifier sources, rollup counts) for a tool with no output schema. It omits pagination behavior even though limit/offset exist, and does not state result ordering beyond 'catalog held first' for the state mode.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences, no filler, and the primary input (name fragment or UNITID) is front-loaded. The second sentence is a long compound clause that takes a second read, which keeps it from a 5.

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 sensibly summarizes the returned fields and the three input-driven result modes. Pagination and the city refinement are left entirely to the schema, which is acceptable given 100% schema coverage but leaves a small gap for a five-parameter 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 reinforces the query parameter (name fragment or UNITID) and the meaning of a state answer, but it never explains the city parameter or the offset/limit contract, adding little 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 names concrete inputs (name fragment, IPEDS UNITID, state) and the concrete payload it returns (identity, sector, identifiers with sources, counts of programs/checklists/learning units). It is clearly a discovery/lookup tool, but it never distinguishes itself from the sibling get_institution, so an agent must infer that find_institution resolves fragments while get_institution fetches by known 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?

It maps each input combination to an outcome: name/UNITID gives one identity, a state gives that state's institutions, and no name plus no state gives the states with counts. That is explicit contextual guidance, though it stops short of naming an alternative tool or stating when-not to use it (e.g., when the id is already known, use get_institution).

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 tells the agent this is a safe read, lowering the bar. The description adds one behavioral fact, that an empty result is reported as 'none held' rather than an error, which is useful. It does not disclose pagination behavior, result ordering, or result shape beyond what the annotations 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?

Very tight: the resource question is front-loaded and the filter list follows immediately. The closing sentence about 'none held' is a little cryptic but short. No wasted text.

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 five-parameter list tool with no output schema and only a readOnly annotation, the description is adequate but thin. It omits pagination semantics and result shape, and gives no comparative context against get_pathway, though the fully specified schema covers the mechanical details.

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 five parameters carry their own descriptions, so the schema does the heavy lifting. The description names three of the filters but adds no syntax, format, or combination semantics beyond the schema, warranting the 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 conveys a specific resource and action: retrieving which pathways are held, with the three filter keys (title words, agreement id, checklist id) named explicitly. An agent can identify it as a multi-result lookup rather than the single-item get_pathway. It stops short of directly distinguishing itself from get_pathway or find_checklists, so it is clear but not fully sibling-differentiating.

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 filter options are listed, which implies usage, but there is no explicit when-to-use or when-not-to-use guidance and no alternative tool is named. Given the crowded sibling set (get_pathway, find_checklists, find_agreements), the description leaves the routing decision entirely to inference.

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 one genuinely useful behavioral note: it returns none rather than erroring when no policies exist for the build. It says nothing about pagination behavior or result ordering, which matters given the limit/offset parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with the resource and scope front-loaded in a question form, and zero filler. The phrasing is slightly unusual but still compact and readable.

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 parameterized lookup with no output schema and full schema coverage, the description supplies enough to call the tool correctly, including the empty-result behavior. Return-shape detail is unnecessary without an output schema, though result structure for pagination is left implicit.

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 limit, offset, unitid and query are all documented in the schema itself. The description only restates the filtering behavior of the query parameter without adding format or syntax detail, which is the expected baseline 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 names a specific resource (academic policies published by an institution) and gives concrete examples (transfer credit, prior learning, tuition and fees), which clearly separates it from the singular sibling get_policy. It does not explicitly name that sibling, 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?

It implies usage via 'Optional words narrow them,' telling the agent the query parameter filters results, but there is no explicit when-to-use or when-not guidance and no named alternative such as get_policy for fetching a single policy.

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 already declaring a safe read, the description still adds value by enumerating the returned fields (award, CIP, verbatim credit figure, edition, source page, institution). Because no output schema exists, this return-shape disclosure is genuinely useful, though it says nothing about pagination or result ordering.

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 compact, but the single sentence is convoluted: it opens as a question, then packs query inputs and output fields into one clause. Front-loading is present ('Which programs match these words') but the mixed structure blurs inputs versus outputs.

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 search tool with no output schema, the description covers the query intent and the return fields, and the schema covers all six parameters. It is close to complete, missing only pagination behavior and ordering/ranking of matches.

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 every parameter including city, state, limit and offset is already documented in the schema. The description only restates query words and the optional UNITID filter, adding no syntax or constraint detail beyond the schema, 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 description states a specific verb (match/find) and resource (programs), and adds scope ('across institutions') that separates it from institution-scoped lookups. It does not explicitly name a sibling like get_program or programs_for_institution, 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 'across institutions' framing and the note that UNITID is optional for narrowing, but there is no explicit when-to-use statement or named alternative. The agent is left to infer that broad keyword search is the entry point and institution-scoping is the fallback.

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 establishes this is a safe read. The description adds one genuinely useful behavioral fact: it returns an empty/'none held' result when nothing exists rather than erroring. It says nothing about pagination behavior or result shape, but with annotations covering the safety profile 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?

Three terse fragments with no wasted words, and the scope of what is held leads the description. The question-style opening is slightly unusual for a tool description but costs nothing in length.

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, and while readOnlyHint plus full schema descriptions cover much of the ground, the description never clarifies how this relates to get_transfer_framework or what pagination/large-result behavior to expect. Adequate but with clear gaps for a finder tool with two get/find siblings nearby.

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, and the baseline of 3 applies. The phrase 'Optional name or jurisdiction words' loosely echoes the query parameter but adds no format or matching-rule detail 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 description states the resource (statewide or compact transfer frameworks) and frames the operation as a retrieval/list question, which is distinguishable from the singular sibling get_transfer_framework. However, the verb is implied rather than explicit and it never names the get_* counterpart, so sibling differentiation is only partial.

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 this versus the closely named get_transfer_framework, find_agreements, or find_comparability. The only implicit condition is that query words are optional, which is not a usage rule so much as a restatement of the schema.

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?

Annotations only declare readOnlyHint=true, so the description's real added value is scope disclosure: which related entities are resolved and included, plus an explicit exclusion ('Signatories name people and are not served'). That clarifies data the agent should not expect without contradicting the read-only 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?

Two tight sentences, front-loaded with the core noun and then the returned payload, ending with a scope caveat. Dense but every clause carries information; nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly carries the return-value burden and enumerates the components returned and the one thing excluded. It is essentially complete for a read-only getter, missing only pagination/envelope details that are unlikely to matter here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema description coverage, and the schema already explains the id comes from find_agreements. The description adds no further parameter meaning, 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?

States a specific verb and resource ('Get... one agreement') and enumerates its returned parts: the row, resolved organizations as parties, and citing pathways/comparability bundles/checklists. 'One agreement' implicitly contrasts with the sibling list tool find_agreements, though it never names it 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 no explicit when-to-use or when-not statement, and no alternative is named in the description. Usage is only implied by the singular framing and by the parameter schema pointing at find_agreements as the id source, so the agent can infer the find-then-get flow.

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 the safe-read profile is covered. The description adds genuine value by disclosing what is returned (row, affiliated institutions, sharing origin, program count). It does not mention return size, pagination, or auth requirements, so it goes beyond annotations but not richly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence, front-loaded with the resource being fetched, with each clause adding a distinct piece of return information. Efficient, though it reads as a noun phrase rather than a directive sentence.

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 it does so by naming the main components returned. For a single-entity lookup this is nearly complete; finer field details would require the response itself.

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 is self-documented with a source hint ('from find_catalogs'). The description adds no additional parameter semantics, 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 specifies the resource (one catalog edition) and enumerates its contents — row, institutions that use it, sharing source, and program count. This lets an agent distinguish it from find_catalogs, the plural finder. It lacks an explicit verb ('get'/'retrieve'), but the resource is 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 when-to-use or when-not-to-use statement in the description. Usage is only implied by the schema's 'A catalog id from find_catalogs', which suggests the intended find_catalogs → get_catalog pipeline. Adequate but leaves the alternative unpinned.

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=true, so the description carries the rest, and it does disclose meaningful behavior: pagination across groups, that the answer reports items_total and next_item_offset, and that each row names its captured source page. It stops short of stating default/limit enforcement or permission needs, but the pagination semantics are a real addition 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 content is dense and em-dash-laden, reading as one long run-on rather than a front-loaded summary followed by details. Every clause contributes information, so nothing is wasted, but the structure makes the core purpose harder to extract 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 no output schema and only a readOnly annotation, the description bears full burden for return-value disclosure, and it does so thoroughly: groups, headers, item counts, credit strings, alternatives, resolved course attribution, and pagination fields. Only usage routing and limit/permission context remain thin.

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 item_limit, item_offset, and checklist_id are already documented in the schema; the baseline is 3. The description reinforces the pagination contract (items_total/next_item_offset) which ties loosely to item_limit/item_offset, but it adds no format or syntax detail beyond the structured 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?

The description opens with a rhetorical framing ('What does this award require?') then states the resource and its returned structure: requirement groups, items with credit strings, alternatives, and resolved course details. This is specific enough to distinguish retrieval-by-id from the search-oriented siblings (find_checklists, compare_program_checklists), though it never plainly says 'retrieves one checklist by its 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?

There is no explicit when-to-use guidance or mention of alternatives such as find_checklists or checklists_requiring_learning_unit. The only routing hint ('a checklist id from programs_for_institution or compare_program_checklists') lives in the input schema rather than the description, so usage is at best 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 mark this as read-only. The description adds useful behavioral context beyond that: it clarifies what the returned bundle contains, including resolution status for source and substitute courses. This helps an agent anticipate output 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 description is one sentence and reasonably brief, but phrases like 'credits awarded published beside any parse' and 'stated unresolved' are awkward and reduce clarity. It earns points for brevity but loses for obscure phrasing.

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 get-by-id tool with no output schema, the description gives a useful overview of the returned bundle. However, it omits what 'parse' refers to and does not explain the practical context of when this result is meaningful. Still, it is mostly adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter comparability_id is fully documented in the schema with a source hint ('from find_comparability'). The description adds no additional parameter detail, but schema coverage is 100%, 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 identifies the resource as one comparability bundle and lists its main contents: the credits row, receiving institution, and source/substitute courses. This separates it from find_comparability by implying a singular fetch, though the wording is indirect and somewhat jargon-heavy.

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?

No explicit guidance is given about when to use this tool versus find_comparability or other sibling tools. The singular 'one comparability bundle' weakly implies retrieval by ID, but there is no stated alternative or exclusion.

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 the safety profile is covered. The description adds important behavioral context: data is 'read as published and never computed' and it explicitly mentions that anything not published for the build is stated. This transparency about data provenance and limitations is valuable 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, dense sentence (with a follow-up sentence) that front-loads the core question and then enumerates what is covered. It is efficient but could be slightly more structured with bullet points or clearer separation of categories for 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?

Given the tool's simplicity (no parameters, no output schema), the description provides a complete picture of what the summary includes and the constraint that only published data is used. It adequately prepares the agent to interpret the output, though it might benefit from mentioning the format (e.g., structured text or JSON) since there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so parameter semantics are not applicable. The description does not need to explain any parameters, and the baseline for zero parameters is 4, which is appropriate here.

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 purpose: summarizing what CourseShelf holds, with concrete details about catalog areas, institutions, row counts, sectors, and verdicts. It distinguishes itself from sibling tools like get_institution or find_programs by focusing on aggregate holdings. However, the initial rhetorical question ('What does CourseShelf hold?') is slightly less direct than a clear 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?

The description implies usage by asking about holdings and enumerating what it provides, but it does not explicitly state when to use this tool versus alternatives like get_institution or list_issuers. No exclusions or alternatives are mentioned, leaving the agent to infer that this is for aggregate summaries rather than detailed queries.

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?

readOnlyHint=true already establishes the safe-read profile, but the description adds substantial behavioral detail: the exact table-by-table return shape, that related collections come back only as counts, and the notable caveat that contacts 'name people and are not served'. It omits auth/size/pagination notes, but for a read tool this is well above the annotation baseline.

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 key statement ('Everything held about one institution') and packs a lot of return-shape information, but it is one long run-on sentence whose enumerations are dense. Nearly every clause earns its place given 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?

With no output schema, the description must carry the return contract, and it does so thoroughly, including the explicit contacts exclusion. The only meaningful gap is invocation routing (when this beats find_institution) and error behavior for a missing id.

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 both parameters carry descriptions with examples (organization_id e.g. ORG_225070, unitid e.g. 225070), so the schema does the heavy lifting. The description adds no syntax or format meaning beyond what the schema already provides, making the baseline 3 correct.

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 crisply conveys that this returns the complete record held about a single institution, enumerated by table (identity, identifiers, addresses, accreditations, costs, calendar dates) plus counts of related collections. The resource and scope are unambiguous, though it never explicitly distinguishes itself from the sibling find_institution.

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 when-to-use guidance: nothing says to call this once you have an id from find_institution rather than search with find_institution or scope down with programs_for_institution. The 'one institution / everything held' framing implies the retrieval use case, but no alternative or exclusion is 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 already cover the safety profile (readOnlyHint=true), so the bar for added context is met by the disclosure that each linked course is 'resolved or stated unresolved — never guessed,' which tells the agent to expect explicit gaps rather than fabricated links. This is a genuine behavioral trait beyond the annotations. It stops short of 5 because nothing is said about response shape, size caps, or pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence, front-loaded with the resource identity ('One course whole') followed by the returned contents. Every clause maps to a return element, so little is wasted, though the long em-dash list is heavier than strictly 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?

There is no output schema, so the description correctly carries the burden of enumerating return contents, and it does so comprehensively for a one-parameter read tool. The only gap is the absence of usage context relative to sibling retrieval tools, which is minor given the simplicity of the input.

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%; the single parameter learning_unit_id is fully documented in the schema, including its source ('from learning_units or get_checklist') and an example value. The description adds no further parameter meaning. Baseline 3 is appropriate when the schema carries the full burden.

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 — a single 'learning unit' (course) — and enumerates exactly what it returns: row, prerequisites, corequisites, aliases, terms offered, articulation statements, comparable members, and transfer frameworks. It is clearly distinguishable from the sibling learning_units (list) by the 'One course whole' framing. It lacks an explicit verb and never names the sibling it is not, keeping it just short of 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 on when to use this tool versus alternatives such as learning_units or get_checklist, and states no prerequisites or exclusions. The only routing hint (where the ID comes from) lives in the schema, not the description. Usage must be inferred entirely from the name.

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 establishes this as a safe read. The description adds genuine value by disclosing the return composition (row plus linked checklist and agreement) and a scope limitation (contacts excluded), but says nothing about permissions, missing-record behavior, or errors.

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, front-loaded sentences with no filler. The telegraphic style ('its row', 'are not served') borders on cryptic and slightly costs readability, but nothing 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?

There is no output schema, so the description carries the return-shape burden; it does name the main payload (row + linked checklist and agreement) but omits key/identifier shape or nested detail. Adequate for a single-id getter, though thin.

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 schema itself documents pathway_id as 'A pathway id from find_pathways'. The description adds no syntax, format, or id-flavor detail beyond the schema, 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?

States a specific resource ('One pathway') and what is returned ('its row and the checklist and agreement it links'), which distinguishes it from the plural find_pathways sibling. The phrasing is terse and 'its row' is jargon-ish, but the verb/resource pairing is 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?

No explicit when-to-use or when-not statement and no named alternative; the agent must infer that this follows find_pathways. The only routing hint ('Contacts name people and are not served') is a data caveat, not usage guidance.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds a real behavioral constraint — only 'published' policies are returned — and describes the returned payload, which is useful given there is no output schema. It does not, however, describe error/not-found behavior or whether the id can be stale.

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 economical sentence with no filler, front-loaded with the resource being fetched. It is a sentence fragment rather than a full clause, but nothing 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?

For a single-parameter lookup with no output schema, the description covers what comes back (section, text, page, edition, source) and the publication scope. The main gap is the absence of usage routing to find_policies, which is minor for such a simple 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% and the single policy_id parameter is documented as coming from find_policies. The description adds nothing about the id 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 names a specific resource — a single published academic policy — and enumerates what it returns (section, verbatim text, page, edition, source). This implicitly distinguishes it from the plural search-oriented sibling find_policies, though the read verb itself is only carried by the name.

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 or mention of alternatives. The 'one ... policy' framing and the schema note ('A policy id from find_policies') imply a lookup-by-id flow, but neither the description nor any exclusions tell the agent when to prefer this over find_policies.

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 the safety profile is covered. The description adds real behavioral context beyond that: this tool returns a fully assembled aggregate (a 'whole' program with offerings campus-resolved and its institution), which tells the agent it does not need follow-up enrichment calls. It does not cover error/pagination behavior for the id lookup.

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 a single, tightly packed sentence with the returned contents front-loaded and the chaining hint at the end. The fragment style ('One program whole:') is slightly informal but costs nothing in length, and no sentence 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 no output schema, the description compensates well by enumerating the returned entities, and with one required parameter at full schema coverage the input side needs nothing more. It stops short of describing nesting/shape of the returned aggregate, but is sufficient for an agent to decide 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%, and the schema already documents program_id with its source tools, so the baseline is 3. The description only adds the mild constraint that a single id is expected ('pass one'), without adding format or provenance 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 names a specific verb+resource (get one program) and enumerates exactly what is returned: row, identifiers, offerings with campus resolved, institution, and award checklists. This clearly separates it from search/list siblings like find_programs and programs_for_institution, though it never names those siblings explicitly.

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: 'pass one' signals a single lookup by id, and the trailing 'pass one to get_checklist' hints at a chaining workflow. However, there is no explicit when-to-use vs when-to-use-something-else guidance (e.g. get_program vs get_institution or vs the find_* tools).

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

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

readOnlyHint=true already establishes this as a safe read. The description adds useful behavioral detail about the payload ('codes with their meanings', courses 'resolved'), hinting at expansion of codes/relationships, but it does not clarify what 'resolved' means operationally or how missing/unmapped data is handled.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with the resource and then the returned components. Slightly fragmentary phrasing ('its row') costs a point but there is no wasted text.

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 only one parameter and no output schema, the description should fully convey the return shape; it does so at a high level (authority, codes, mapped courses) but leaves 'row' and 'resolved' undefined, so an agent has a rough but not complete picture.

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 single framework_id parameter and its origin are already documented in the schema. The description adds no further parameter semantics, making the baseline 3 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 resource and enumerates the returned contents (row, authority, codes with meanings, mapped courses), which lets an agent distinguish it from the list-oriented sibling find_transfer_frameworks. It does not explicitly state the verb, but the get-by-id intent is unmistakable from the schema.

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: fetch one framework, and the schema's framework_id description points to find_transfer_frameworks as the source of ids. There is no explicit when-to-use versus when-not, nor a statement of prerequisites, so guidance is only inferred.

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 safety is covered. The description adds notable behavioral detail: the credit string is kept verbatim with ranges preserved, and it discloses page capture. However it omits pagination mechanics beyond what the schema says and no return 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?

Front-loaded with a question framing the tool's purpose, then a compact clause packing filters and output semantics. Dense but no obvious waste; slightly long single sentence.

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 7-param read-only list tool with no output schema and 100% schema coverage, the description covers purpose, filters, and key output guarantees (verbatim credits, edition, page). Pagination via offset/next_offset is only referenced in schema, and no return structure is given, but the essentials are present.

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 value beyond the schema: it clarifies 'spaces and case ignored' for code and that the filter matches subject abbreviation, course code, or title words. That extra matching semantics goes beyond the schema 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?

Clear verb+resource: it lists published courses for an institution and names the filters available. It distinguishes itself from siblings like get_learning_unit (singular) and search_certifications, though it doesn't explicitly name an 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?

The lead question implies usage (querying an institution's course catalog with filters), but there is no explicit when-to-use vs when-not, nary a mention of the singular get_learning_unit alternative. Usage context 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?

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?

Annotations include readOnlyHint=true, which signals that the tool is safe and non-mutatingley. The description adds useful context about the output fields (checklist IDs to pass to get_checklist), which helps the agent understand the data flow. However, it does not disclose other behavioral details such as pagination behavior (though the offset parameter and limit suggest pagination), rate limits, or any potential large response sizes. The description does not contradict the annotations, so a 3 reflects that it partially compensates 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 single, information-dense sentence that lists the outputs and the connection to get_checklist. It is concise and front-loads the core question ('What programs does this institution publish?'), making it easy for an agent to scan. It loses one point because it might be slightly packed with technical terms (CIP, credential class) that could be clarified, but overall it 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 complexity (multiple fields returned, relationship to checklists, pagination via offset), the description provides enough context to understand the tool's role. The output schema is absent, so the description's enumeration of returned fields partially compensates. However, it does not explicitly mention pagination behavior or the possibility of multiple pages, which is relevant given the limit and offset parameters. An agent might need to infer they should use the returned next_offset to fetch all results. This is a minor gap, so a 4 is appropriate.

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 explains each parameter: unitid is the institution's IPEDS ID, query filters by program/award words, limit sets page size, and offset is for pagination. The description adds minimal extra meaning about parameters; it mentions 'checklist ids to pass to get_checklist' but that's output-related, not param-specific. Since the schema does the heavy lifting, the description's contribution is marginal, hence a baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the purpose: listing programs an institution publishes, and enumerates the exact fields returned (award, credential class, CIP, published credit figure, catalog edition, captured page, checklist IDs). It distinguishes this tool from siblings by focusing on institution-level program data, whereas siblings like get_checklist or certifications_for_program target different resources.

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: when you need programs for an institution male. However, it does not explicitly state when NOT to use this tool, nor does it mention alternatives among the siblings. For example, it does not say 'use certifications_for_program for certifications' or mention any exclusions. The context is clear for institution-level program lookup but lacks explicit guidance on choosing among similar tools.

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

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

Annotations 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?

Annotations declare readOnlyHint=true, so the safety profile is covered; the description goes further with semantic constraints (3-character minimum for course words, mandatory location scoping for very common words) that materially affect how the tool is called. It spends some words restating the return card contents, which the output schema already covers, so it is not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core content is delivered as one sprawling, comma-chained sentence that is hard to parse, followed by a constraint sentence. The opening question is a soft lead-in rather than a crisp front-loaded statement of purpose.

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 15-parameter optional-filter tool with an output schema and read-only annotation, the description covers the main filter families and the two operating constraints, which is close to adequate. It omits mention of pagination-related params (limit/offset) and the code param, but the schema carries those.

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 echoes several filters (subject/CIP family, subject prefix, credential class, award, state/city/type/UNITID) but adds no syntax or format meaning 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 by framing the search domain ("Which programs or courses match, and where?") and enumerates the filter dimensions (words, CIP subject, subject prefix, credential, award, school location/type/UNITID), so the verb+resource is discernible. It does not, however, distinguish itself from close siblings like find_programs or learning_units, leaving the agent to 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?

There is real conditional guidance: courses need words of 3+ characters, and words held by very many courses require a state, city or school to narrow. But there is no when-to-use-this-vs-alternatives guidance despite several overlapping siblings, so usage is implied rather than routed.

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?

Annotations provide only readOnlyHint=true, so the description carries the behavioral load. It goes beyond that by explaining the three-state output, that it 'never a guess', that it cites specific rules with scores and dates, and that it is 'a case to argue, not a verdict' – making the tool's behavior and limitations explicit. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence contributes: it leads with the core question, then specifies the inputs, the three states, the details of covered items, and ends with a crucial caveat about the tool's advisory nature. It is front-loaded and structured with semicolons, though slightly verbose compared to a minimal two-sentence description.

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 3 parameters, a detailed output schema, and the readOnlyHint annotation, the description is remarkably complete. It explains the tool's domain, the input semantics, the result states, the level of detail in the answer, and the philosophical stance ('not a verdict'). An agent has enough to invoke it correctly without needing to guess about missing behavior.

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 has a description, so the baseline is 3. The description adds meaning beyond the schema by explaining how 'held' items (exams/courses) are processed against the target school's rules, how the three-state result is derived, and what the answer includes. It doesn't detail every parameter, but it enriches the schema's existing explanations.

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 pair: it evaluates whether prior credits will transfer to a target school, and details the three output states (covered, missing, unknown) and the information returned for covered items. This clearly distinguishes it from siblings like find_comparability or suggest_credit_for_my_learning by naming its specific inputs (AP/CLEP/IB exams or courses) and the use of the target school's published transfer rules.

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 clearly establishes when to use this tool: when a person wants to know if their held credits will apply at a target school, with a specific scenario described. It does not explicitly name alternatives or exclusion criteria, but the context is unambiguous enough for an agent to select it over sibling tools like suggest_credit_for_my_learning.

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