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

Annotations already declare readOnly/idempotent/openWorld and non-destructive, so the safety profile is covered; the description usefully adds that the site has no price filter. However, the clause 'no price filter or sort on the site' reads as if sorting is unavailable while the schema exposes a 'sorting' parameter (manual/popular/new/rate), which could make an agent skip a supported capability. Net: some added value plus one confusing statement.

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 lines with the capability first and the routing/exclusion notes second; nothing is padding. The only weak sentence is the 'no sort' clause, which spends words creating ambiguity rather than removing it.

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 10-parameter, zero-required, fully-schema-documented browse tool with no output schema, this is close to complete: scope, filters, prerequisites and alternatives are all present. Minor omissions are the pagination/total-count behaviour and a clear statement of what 'sorting' actually does.

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, and the description goes beyond it by explaining the provenance of category_slug and organization_ids (which upstream tools supply them) and by sizing the corpus (~5700). It does not clarify the ambiguous 'sorting' vs 'no sort' point, which is the remaining gap.

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

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

States a specific verb and resource ('List courses') plus the scope ('a category, or all ~5700') and enumerates the filter families it accepts. It also names the siblings it is not (mkh_search for text, mkh_cheapest for price), so an agent can route without opening any 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?

Explicit when-not guidance: 'No text query here (use mkh_search)' and 'for price use mkh_cheapest'. It also tells the agent where prerequisite identifiers come from ('category slugs from mkh_categories, publisher ids from mkh_organizations'), which blocks the most likely invocation error.

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 safety profile is covered. The description adds genuine behavioral context: tree depth semantics, node volume, and that this is the slug source for other tools, which warns the agent about a prerequisite/dependency chain. Return field shape is still unstated.

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

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

Extremely compact and front-loaded: the consumer relationship comes first, then the mode selector. Slightly telegraphic phrasing ('query = title search with path') costs a little readability but 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?

A tree-listing tool with no output schema should tell the agent what a node looks like (slug, title, child count, path) and whether the whole tree can be returned at once. The description conveys scale and access modes but not the response structure, leaving a real gap for a zero-required-param tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds value beyond the schema by explaining mode interaction: no args yields the 11 top-level groups, slug selects one subtree, query does title search with path. This clarifies how the parameters compose, which the schema fields alone do not.

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 (category tree), its size (~680 nodes in 11 top-level groups), and its primary output contract: slugs consumed by mkh_browse, mkh_free_courses, mkh_cheapest and mkh_deals. An agent can immediately tell this apart from sibling tools that consume those slugs.

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 enumerates the three invocation modes — no arguments for top-level groups, slug for one subtree, query for title search — which covers the main when-to-use cases. It does not state when to prefer it over mkh_search for keyword lookup, leaving one routing ambiguity.

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?

Adds substantial behavior beyond the readOnly/idempotent annotations: the site cannot sort by price, so it scans the first 300 results (relevance-ordered for queries, popularity otherwise) and sorts locally. It also explains that `scanned` of `total` signals answer completeness — critical to interpreting a truncated result set.

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 purpose, then the caveat, then the next-step pointer — a good information order. Slightly verbose with the awkward line breaks and parenthetical asides, but 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?

For a 7-parameter, no-output-schema tool, the description covers result interpretation (scanned/total) and the caps on search coverage, which is what an agent most needs. Pagination behavior and the exact result fields beyond price are left implicit, so not 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 coverage is 100%, so baseline would be 3, but the description adds genuinely new semantics: when `query` is set, category and type/level are silently ignored, which the schema alone does not convey. Price/limit semantics remain schema-only.

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 and ordering: 'Cheapest paid courses for a topic or category, ascending by final_price (what the customer pays).' This clearly separates it from siblings like mkh_free_courses and mkh_deals, and the trailing 'Next: mkh_course' hints at the follow-up 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?

Gives concrete usage context: 'With query, category and type/level are ignored' tells the agent how parameters interact, and 'Next: mkh_course' suggests a chained call. It does not explicitly contrast with mkh_deals or mkh_free_courses, though the 'paid' scoping implies the boundary.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description contributes genuinely useful domain context beyond that: prices are in Toman, and the full/content_only/upgrade tiers are defined so the agent can interpret the response correctly. This is real added value but doesn't address coverage gaps 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?

Extremely dense and front-loaded: the return contents come first, then pricing semantics, then next-step routing. The telegraphic fragment style ('Prices are Toman.') is efficient, though the opening field list is a bare noun phrase that reads slightly like a label rather than a 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?

No output schema exists, so the description carries the burden of describing what comes back, and it does so by enumerating the returned fields and defining the pricing tiers. Combined with annotations covering the read-only profile, an agent has enough to invoke it correctly and interpret results.

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 course_id parameter already documents its source (mkh_search or mkh_browse) and an example. The description adds nothing about the parameter, 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?

Opens with a specific verb-less but unambiguous statement of resource and scope ('One course') and enumerates the exact fields returned (prices, discount end, level, hours, teachers, publisher, prerequisites, FAQ). It also names the natural follow-on siblings mkh_curriculum and mkh_reviews, which separates it from the list/search-oriented siblings without restating their 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 'Next: mkh_curriculum, mkh_reviews' line gives a clear navigation hint for what to call after this tool. However, it never states when to choose mkh_course versus mkh_search or mkh_browse, nor that course_id must first come from a search/browse call in prose terms.

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 (readOnly, idempotent, non-destructive). The description adds genuinely non-obvious behavior beyond them: long courses are cut at 200 lessons and a truncated=true flag is returned, which matters for completeness of results. Return format of the remaining fields is still not spelled out.

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, zero waste, with the returned content front-loaded and the sibling-routing note placed last where it belongs. Nothing repeated from the name or schema.

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

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

For a one-parameter read tool with no output schema, the description covers what comes back, the truncation cap and its flag, and where to go for the fields it deliberately omits. An agent has everything it needs to call it and interpret the result.

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

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

Schema coverage is 100% and the single course_id parameter is fully documented in the schema, including its origin (mkh_search or mkh_browse) and an example. The description adds no parameter detail beyond that, 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?

Names a specific resource (chapters and lessons of a course) with the attributes it returns (type, duration), and explicitly routes the agent to mkh_course for price/teachers/description. An agent can distinguish it from mkh_course without opening either 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?

Gives an explicit alternative and the condition that selects it: use mkh_course when you need price, teachers, or course description. It doesn't state prerequisites (e.g., that course_id must come from a search first), but the routing guidance is clear and concrete.

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 annotations, the description discloses important behavior: it scans the 300 most popular paid courses of the category and filters from there, sales are time-limited, and discount end dates must be retrieved via mkh_course. This adds meaningful operational context that the annotations do not provide.

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 short and front-loads the core result: discounted courses sorted by discount. The return fields and follow-up tool are packed efficiently, though the terse 'Next: mkh_course.' ending is slightly abrupt.

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 fully described input parameters, the description covers scope, sorting, key return fields, and the time-limited nature of sales. It does not fully explain pagination or response shape, but no output schema exists and the core behavior is adequately described.

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 parameters are already well documented with defaults, bounds, and examples. The description reinforces category scope and filtering behavior, but it does not add parameter-specific semantics beyond what the schema already 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 clearly identifies the resource as currently discounted courses, states the sort order as biggest discount first, and names the returned discount/price fields. It distinguishes this from free or cheapest-course siblings by focusing on active discounts, though it does not explicitly contrast alternatives beyond pointing onward to mkh_course.

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 title and description: the tool is for finding courses that are currently discounted. It gives an explicit next step ('Next: mkh_course') for discount end dates, but does not say when to prefer this over siblings such as mkh_cheapest or mkh_search, nor does it state 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the meaningful domain caveat that free viewing may still involve paid certificates, plus an approximate result count, but it omits pagination and return-shape behavior.

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

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

The description is short and front-loads the key scope: free courses at final_price 0. The parenthetical about categories is awkward, but overall it avoids unnecessary 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?

For a six-parameter listing tool with full schema coverage and read-only annotations, the description covers what is listed and clarifies what 'free' means. It does not describe return fields or pagination, but the schema handles parameters and there is no output schema to explain.

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 parameters are already fully documented. The description's only parameter-like claim, 'optionally in one category: hours, rating, students', does not map to any schema parameter and risks misdirecting an agent rather than adding meaning.

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

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

States a specific verb and resource: list free courses with final_price 0, about 740 of them. It is clear what the tool returns, but it does not explicitly distinguish itself from siblings like mkh_cheapest or mkh_deals, and the 'category: hours, rating, students' phrase is confusing.

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 useful context that free courses are watchable without paying while certificates may cost, and points to mkh_course as a next step. However, it does not say when to use this instead of mkh_cheapest or mkh_deals, nor does it state any 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds useful behavioral detail beyond that: the return content (totals plus most popular courses) and implicit ordering. It lacks pagination/rate-limit notes, but with the annotations carrying the safety burden, this is solid.

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 padding; the return content comes first and the routing hint second. The 'Next:' fragment is terse to the point of being slightly telegraphic, but it is efficient and easy to scan.

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 full schema coverage and annotations covering the safety profile, the only remaining burden is describing the return, which the description does (totals and popular courses). No output schema exists, yet the summary is adequate for an agent to know what it gets back; finer return-shape detail is the only gap.

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

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

Schema description coverage is 100%, so both parameters (org_id, limit) are already documented in the schema, including the 'most popular first' ordering and the org_id source. The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description names a specific resource (a publisher's profile) and specifies what it contains: totals for courses, students, rating, plus most popular courses. That is enough to distinguish it from mkh_browse, which is framed as the filtered/paged list alternative. It stops short of a explicit verb ('get/retrieve') and doesn't explicitly contrast with the sibling mkh_organizations 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?

The 'Next: mkh_course, or mkh_browse with organization_ids for filters and paging' line tells the agent what to reach for after and when to prefer browse instead (filtering/paging). It doesn't state a when-not condition for this tool itself, nor when to pick mkh_organizations first, but the routing 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?

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds non-obvious behavior an agent could not get from annotations: names are derived from the site map and word separators are approximate, which warns against exact-string matching.

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 blocks, front-loaded with the resource definition before the routing hint. The line-broken fragments are slightly choppy but nothing is redundant.

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

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

For a read-only lookup with full schema coverage and no output schema, the description covers purpose, data caveats, and next steps. Only pagination/return-shape details are unaddressed, which is a minor gap given the annotations.

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 both limit and query are documented at baseline 3. The description adds the downstream semantics of the id (usable as organization_ids in mkh_browse), which is meaning the schema does not carry.

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 specific resource (course publishers, ~180 of them) and clarifies the output is ids used as filters, which separates it from mkh_browse and mkh_categories. The verb 'list' is only implicit, and the fragmentary first sentence keeps it just 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 explicitly routes the agent: use mkh_organization for detail on one entry, or feed an id into mkh_browse via organization_ids. That is a concrete when-to-use-this vs. when-to-use-sibling instruction rather than an implied 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 cover readOnly/idempotent/non-destructive, so the description isn't needed for safety. It adds real value beyond them: the response includes a star histogram, reviewer names are deliberately omitted (privacy), and review text is untrusted third-party content that must not be followed as instructions. Pagination behavior is hinted via the 'Next' pointer rather than explained.

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 what the tool returns, then the safety caveat, then the follow-up pointer. No waste, though "Next: mkh_course" is tersely telegraphed and could be slightly clearer.

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 return-shape burden and does so by naming the fields and the histogram. Combined with full schema coverage and annotations, an agent has enough to call and interpret this correctly; only paging/return-size expectations are 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%, with limit, offset and course_id all documented including the next_offset paging convention and id provenance. The description adds nothing about parameters, 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+resource: learner reviews of a course, and enumerates the returned fields (stars 1-5, text, date, instructor reply) plus the star histogram. It doesn't explicitly contrast with siblings like mkh_course or mkh_teacher, 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?

"Next: mkh_course" implies a workflow step (view course details after reading reviews), which is some guidance. But there is no explicit statement of when to use this versus mkh_course, mkh_search or mkh_browse, and no 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?

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so safety is covered. The description adds a genuinely non-obvious constraint beyond the annotations: only the first 300 matches are reachable and the total is capped at 300, which materially shapes how an agent queries. It stops short of describing pagination interaction with that cap (e.g. whether page 1000 with limit 50 is reachable), so 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?

Two compact blocks: the search scope and returned attributes first, then the cap constraint and routing to alternatives. No filler sentences; every clause carries actionable information.

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

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

There is no output schema, and the description compensates by naming the fields the results carry. Given a simple 4-parameter search tool, the disclosed cap, the absence of filters, and the next-step tool, an agent has everything needed 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 description coverage is 100%, with each of the four parameters (query, page, limit, sorting) documented in the schema including defaults, bounds and the sorting enum, so baseline 3 applies. The description corroborates the query semantics (Persian or English free text) but adds nothing about page/limit/sorting behavior.

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 ('Full-text search of courses by title/topic') and enumerates the attributes surfaced (price, discount, hours, rating, students, teachers), which lets an agent distinguish it from the browsing siblings. The closing pointer to mkh_course further pins down its role in the toolset.

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 the site offers no filters here and names three concrete alternatives (mkh_browse, mkh_free_courses, mkh_cheapest) for level/price/type/category filtering, plus the follow-up step (mkh_course for a single id). When-to-use and when-not-to-use are both spelled out.

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, open-world behavior, so safety is covered. The description adds real value by disclosing the return payload (profile fields plus priced courses), but says nothing about behavior for unknown slugs or about how the course list is bounded, so it stays at a baseline-plus level.

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 fragments, with the resource and its contents front-loaded and the follow-up pointer kept to one line. The 'Next:' line reads a bit like an inline navigation hint rather than description prose, 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 read-only, two-parameter tool with no output schema, the listed return fields provide most of what an agent needs to decide whether to call it. The only gap is edge-case behavior for an invalid or ambiguous slug.

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 the slug format and example already documented, so the schema already explains both parameters. The description only implicitly explains what 'limit' controls through 'their courses with prices' and adds no new parameter constraints, so it is 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?

Names a specific resource (teacher profile) and enumerates the fields returned (bio, students, rating, teaching hours, links) plus the attached courses with prices, which clearly separates it from mkh_course, which handles a single course.

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 'Next: mkh_course for one of the courses' line gives a useful follow-up path, but there is no guidance on when to choose this over mkh_search, mkh_organization, or mkh_browse, and no stated precondition beyond the schema's note that the slug comes from a course.

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