Publisher profile

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.