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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered without the description. The description adds content-level context (that version info includes a source git SHA and search-index build time, and that license/child-safety notes are included), which is genuinely useful and not in the annotations. It stops short of describing return structure or freshness guarantees.

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 short sentence with no filler — every listed element corresponds to real returned content. It is slightly weakened by being a bare fragment with no leading verb, which makes the first read feel like a field dump rather than a statement of what the tool does.

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

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

No output schema exists, so the description carries the burden of explaining return values, and it does list the four buckets of returned data. But it gives no sense of structure, key names, or scale (e.g. how counts are grouped), which for a zero-parameter inspect-the-catalog tool is only a partial account.

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 per the rubric the baseline is 4. There are no inputs whose semantics could be ambiguous, and the schema is fully documented. No deduction is warranted.

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 enumerates the categories of information the tool surfaces (item-type counts, content version, level mapping, license and child-safety notes), which is more specific than the title alone. However, it is a verbless noun fragment — it never states that the tool *returns* catalog-wide metadata, so the action is only inferred. It does at least distinguish itself from item-level siblings like get_item and list_courses.

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 reach for this tool versus list_courses, list_subjects, list_age_bands, or the other catalog-adjacent siblings. No prerequisites, no context, no exclusions are given. The agent must guess that this is the whole-catalog overview rather than a filtered listing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds the ordering guarantee and the presence of item_id in each entry, which is useful return-shape context, but says nothing about pagination, empty results, or invalid course_id behavior.

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

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

Two short sentences with no filler, and the core scoping fact (course_id sourced from list_courses) is front-loaded. The first sentence is slightly compressed and reads awkwardly as a fragment, 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?

With no output schema, the description carries the burden of describing returns; it does state entries are ordered and carry an item_id, which is the key shape information. It leaves gaps around what a 'sitting' is, whether results are paginated, and what an error response looks like, but for a simple annotated read tool this is close to adequate.

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

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

Schema description coverage is 0% for the single parameter, but course_id is largely self-explanatory from its name. The description does add provenance value by stating it comes from list_courses, which is more than the bare schema offers, though no format, length, or validation context is given.

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 the resource (ordered chapters/sittings for a course) and its granularity (each entry has an item_id), which is enough to tell it apart from siblings like get_item or search_content. It stops short of an explicit verb, reading as a noun phrase rather than 'retrieves the ordered outline of...', but the intent 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?

The phrase 'a course_id from list_courses' implies the prerequisite that list_courses must be called first to obtain the id, which is genuine routing guidance. However, there is no explicit when-to-use/when-not statement or mention of alternatives such as get_item for drilling into an individual entry.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing what each include mode returns (metadata/excerpt/media/prompt, chapter text, stored body). It does not cover failure behavior for an unknown item_id.

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

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

Three sentences, front-loaded with the core action, then progressively detailing each include mode. Every sentence carries distinct information and no padding is present.

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 characterize returns, and it does so per include mode. For a simple two-parameter read tool this is nearly complete; only error/not-found behavior and item_id expectations are 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 description coverage is 0%, so the description carries the full burden and does largely meet it: it defines the meaning of all three enum values for include and their additive relationship (chapters adds to summary, full adds body). item_id is only implied by 'one catalog item' – no format or constraint guidance is given.

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: 'Fetch one catalog item.' That contrasts implicitly with siblings like search_content (multi-result) and list_* (enumeration), though no sibling is named explicitly. Clear enough for an agent to select it when it already has an item_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 three include modes give practical guidance on how much to request, which is a form of usage steering. However, there is no explicit when-to-use/when-not-to-use statement versus alternatives such as search_content or get_media_urls, nor any prerequisite 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds one genuinely useful behavioral fact — that learner_profile is not stored — but says nothing about auth, rate limits, or whether the returned 'seed' is cached or generated on demand.

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 filler: the first front-loads the return payload and the second handles the one behavioral caveat. The opening sentence is a dense comma list rather than a purpose statement, which slightly hurts front-loading of the core action.

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

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

With no output schema, the description usefully enumerates what is returned, which is the main completeness requirement here. It is still thin on item_id semantics and on what the enumerated artifacts look like (e.g., format of 'printable links'), but for a read-only retrieval tool it covers the essentials.

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 0%, so the description carries the burden, and it partially compensates by explaining that learner_profile is optional and not persisted. However, it never explains item_id (the required parameter), nor does it map any of the nested learner_profile fields (age, interests, learning_style), leaving the enum-bearing nested object undocumented.

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 enumerates the specific payload this tool returns (objectives, Hermes pairing line/prompt, discussion questions, activities, cautions, printable links) for an item, which is concrete and lets an agent infer it is a lesson-plan retrieval tool. It stops short of a clear verb-object opener and does not differentiate itself from the sibling get_item, which plausibly returns related item data.

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 call this versus get_item, get_course_outline, or the other retrieval siblings, and no prerequisite or context conditions are stated. The only conditional language ('learner_profile is optional') is parameter framing rather than 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 readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavioral context: no byte proxying (the caller must fetch the URL itself) and that MIME type and size are returned only 'when known'. It does not mention auth requirements or ordering of results.

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, no filler, and the return-shape information is front-loaded ahead of the parameter note. Every sentence carries distinct information (what is returned, what is not provided, how to filter).

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 burden of describing the return (URLs plus MIME type and size when known), which is the essential information for a read-only lookup tool. Minor gaps: no note on result ordering, empty-result behavior, or whether URLs expire.

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 0%, so the description must compensate — and it does for 'kinds': it lists the accepted kinds and, crucially, discloses the default behavior when omitted ('omit it for every kind'), which the schema does not. It never mentions 'item_id' or its expected format, leaving one of two parameters undocumented.

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 ('Public media URLs for an item') and enumerates the concrete kinds returned, so an agent immediately knows this retrieves links rather than content. It does not explicitly contrast with the closest sibling (get_item), but the resource is specific enough to be distinguishable.

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

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

Usage is implied rather than stated: 'The server does not proxy bytes' tells the agent this yields URLs for client-side fetching, but there is no explicit when-to-use or when-to-prefer-an-alternative guidance versus get_item or search_content. Adequate but with a clear gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so the safety and repeatability profile is fully covered structurally. The description's added value is disclosing the shape of the returned data (four fixed entries, each with ranges, promises, and level mapping), which matters because no output schema exists. It does not add ordering, count stability, or pagination context beyond that.

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 with no filler, and the most important fact (there are exactly four bands) is front-loaded. It is a noun phrase rather than a sentence, which reads slightly like a label, but nothing is wasted and nothing important is buried.

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 parameters, no output schema, and annotations carrying the full safety profile, the only real burden is describing what comes back — and the description does that by listing the three fields per band. The tool is simple enough that nothing critical is missing; only the relationship to list_by_age_band 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The schema is empty and correctly so for a static reference listing.

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 the exact resource (the four WisdomForge age bands) and enumerates what each entry contains: age ranges, promises, and booklet level mapping. That is enough for an agent to know this is a taxonomy lookup. It stops short of distinguishing itself from the similarly named sibling list_by_age_band, which is the one ambiguity an agent would face.

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 and no named alternative, even though list_by_age_band and list_subjects sit right beside it. The usage is implied by the content: call this to obtain the canonical band taxonomy (e.g. to resolve an age range to a band label) before calling list_by_age_band. Implied but not 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 declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real context beyond them: the cursor is opaque, nextCursor is passed back for the next page, and the default limit is 20. Return shape details beyond the cursor hint are still absent.

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?

Four short sentences, front-loaded with purpose and followed by filters and pagination mechanics; every sentence carries information. The enumerated content-type list is slightly verbose but justified for scoping.

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 discloses the pagination contract (opaque cursor, nextCursor, default limit) that an agent needs to iterate pages. What remains thin is the age-band enum semantics and differentiation from sibling search tools.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for cursor (opaque, echo nextCursor back), limit (default 20), and the subject/type filters. It does not explain the band parameter beyond "one age band," nor that it is required or what the four band values mean.

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 (page) and resource set (lessons, books, booklets, audio, demos) scoped to one age band, plus the filter axes. It is clear what the tool returns, but it never contrasts itself with the similar sibling search_content, so sibling differentiation is left implicit.

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

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

"Optional subject and type filters" and the pagination instruction imply browsing-by-band usage, but there is no explicit when-to-use or when-not-to-use guidance versus search_content or list_courses. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two genuinely useful behavioral facts beyond that: results are sorted by title and each row carries ordered item ids. It says nothing about pagination, result size, or what happens when no band/subject is supplied.

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 no obvious padding, and the return-shape fact is front-loaded. But the middle sentence is dense domain jargon ('a subject unit's sittings') that costs more reading than it repays, and the ordering detail is split awkwardly from the row-content detail.

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

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

With no output schema, the description does useful work by stating the sort order and that rows contain ordered item ids. For a two-parameter filtered list tool, though, the absence of any filter semantics, optionality, or pagination behavior leaves real gaps for correct invocation.

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

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

Schema description coverage is 0% for both parameters, so the description must compensate and largely does not. The phrase 'for one band' hints at the band parameter but never explains what a band is, and the subject parameter is not referenced at all; it is also unstated that both filters are optional and that omitting them returns the full catalog.

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 defines the domain concept ('A course is a book or a subject unit's sittings for one band') and says rows include ordered item ids, so the agent can infer it returns course listings in title order. However, it never states the action plainly ('lists all courses') and the opening phrase 'Books and lesson tracks in title order' is ambiguous about whether books and lesson tracks are the returned entities or something else. It does not differentiate itself from siblings like get_course_outline or list_by_age_band.

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 and no mention of alternatives, despite siblings such as get_course_outline, list_by_age_band, search_content, and get_catalog_info that plausibly overlap. The agent is left to guess whether this is the browse-everything call or a filtered one.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: the result set is capped at ten subjects, index documents are excluded from counts, and band narrows the counted population. Return format/ordering is not described.

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 sentences, front-loaded with what the tool returns, then the parameter effect, then the counting exclusion. No filler and nothing repeated from structured fields.

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 tool with one optional enum parameter and no output schema, the description covers result size, count semantics, and an important exclusion. It is nearly complete, with only minor gaps such as ordering or what counts as a subject.

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 0% for the single 'band' parameter, so the description must compensate, and it does explain that band limits which items are counted. However it never explains the enum values (little/young/emerging/adult) or defaults, so the semantics are only partially covered.

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

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

States a specific verb+resource ('List subjects') with item counts and a ten-item cap, which is concrete enough for an agent to know what it returns. It does not distinguish itself from nearby siblings like list_age_bands or list_by_age_band, so it falls short of a 5.

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

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

The only usage instruction is about the band parameter ('Pass band to count only items in that age band'), which is parameter behavior rather than tool-selection guidance. No when-to-use, when-not-to-use, or alternative (e.g. list_by_age_band) is named.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: ranking is deterministic, no model/LLM call occurs, nothing is persisted, and cross-age-band results are filtered out. It does not describe the response shape or ordering guarantees, which keeps it out of 5 territory.

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?

Five short sentences, no filler, and the core purpose is front-loaded before the mapping tables. The band and style mappings are dense but each clause adds real information; the only mild weakness is that 'Other bands are excluded' is terse enough to be slightly ambiguous about what exactly is excluded from.

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 6-parameter recommendation tool with no output schema, the description covers the ranking logic well but omits what the caller receives (item shape, ordering, default/max limit behavior) and how subjects, interests, and exclude_ids influence or filter the ranking. Annotations cover safety, but the return-value and non-required-parameter gaps leave the definition only minimally complete for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does so well for the two required parameters — age is mapped to explicit bands (<=10 little, 11–14 young, 15–18 emerging, 19+ adult) and learning_style drives a documented boost toward audio, books/printables, images/art, or lessons with a 'Try This'. However, limit, subjects, interests, and exclude_ids receive no interpretation at all, leaving four of six parameters undocumented in both schema and prose.

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 (deterministic ranking of content for a single learner request) and details the ranking rules by age band and learning style, so the agent understands the resource being produced. It falls short of a 5 because it never names the siblings it could be confused with (e.g. search_content / list_by_age_band) or explicitly says it returns a ranked recommendation list.

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 statement of when to reach for this tool versus search_content, list_by_age_band, or the other catalog siblings, and no prerequisites are given. The only usage-adjacent information is the behavioral note that other age bands are excluded from results, which is a filtering rule rather than guidance on tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context about how ranking works (BM25 index for corpus docs, same tokenizer over catalog titles/excerpts), but says nothing about result shape, scoring fields, or empty-result behavior.

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

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

Three tight sentences, front-loaded with the action and resource, then mechanics, then parameters. The BM25/tokenizer sentence is denser than strictly necessary but earns its place by explaining why catalog titles and corpus documents are searched differently.

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?

Six parameters, three enums, and no output schema, so the description should ideally sketch what comes back (ranked items, scores, hit count). It covers the input side well but leaves return values entirely unaddressed; annotations at least carry the read-only/idempotent profile.

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

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

With 67% schema coverage, the schema documents band, limit, query, and figure but leaves type and subject bare. The description compensates by naming all four optional filters and restating the default limit of 10, adding the key fact that these narrow rather than require.

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: 'Rank WisdomForge items for a query.' That clearly separates it from the get_*/list_* siblings, which retrieve known items rather than rank by relevance. It stops short of naming any sibling explicitly, so it is clear but not differentiated by comparison.

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 (have a free-text query, optionally narrow by band/subject/type/figure) but never says when to prefer this over recommend_for_learner or list_by_age_band. No exclusions or preconditions are given, so the agent must infer the routing.

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