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

Annotations cover the read-only/idempotent/open-world profile, but the description adds real behavioral context the annotations cannot: per-type return rendering (images as viewable images, text as text, PDFs as embedded files depending on client) and a hard 10 MB size limit. That is genuine value beyond structured fields.

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 the action and examples, then the return behavior and the size cap. No filler; the multi-sentence structure is justified by the different return types.

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-param fetch tool with no output schema, the description covers accepted inputs, return modality per file type, and the 10 MB limit. Only minor gaps remain (what happens on oversized/failing fetches, pagination not applicable).

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 'url' param, so the description must carry the meaning, and it does via concrete accepted URL formats ([image: ...], piazza.com upload links). It stops short of format/encoding details, but the examples are useful compensation for the coverage 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+resource ('Open a file or image that a post links to') and gives concrete examples of acceptable URL shapes. No sibling does this, so it is clearly distinguished from the listing/reading tools in the sibling set.

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 examples (an [image: ...] link or a piazza.com upload link) but the description never says explicitly when to use this vs. reading a post directly, nor any preconditions. Adequate but not routing-level 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, idempotentHint and openWorldHint, so the safety profile is covered. The description adds that staff names, roles and emails are returned, but says nothing about auth needs, rate limits, or missing-course 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 sentences, zero filler, with the returned content front-loaded and the usage scenario second.

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 need not be explained, and annotations carry the safety profile. The only real gap is the ambiguous format of the course identifier, which an agent needs 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?

There is one required parameter (course) with 0% schema description coverage. The description never clarifies whether "course" is an ID, a code, or a title, so it fails to compensate for the schema 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 (get) and resource (course page) and enumerates the exact content returned: description, syllabus, office hours, dates, staff list. This clearly separates it from get_course_stats (numbers) and the post-related 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?

"Use it to find who teaches the course or when office hours are" gives a concrete selecting scenario. It provides no exclusions or named alternatives, but the context is clear enough for routing.

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

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

Annotations already declare readOnly, idempotent, openWorld behavior, so the safety profile is covered. The description adds a genuine access caveat — instructors may hide the Statistics page from students — but does not say whether that yields an error, empty data, or a permission denial, so the behavioral disclosure is incomplete.

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

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

Two short, front-loaded sentences with no wasted words. The caveat is placed after the core purpose, which is appropriate. Brevity is good, though it comes partly at the cost of specificity.

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 need not be described. However, for a single-parameter tool with zero parameter documentation and an ambiguous access caveat, the description should say more about the identifier and the failure mode when the page is hidden.

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 one required parameter ('course') with 0% schema description coverage, and the description does nothing to clarify it — no indication of whether it is an ID, short name, or display name. The description's reference to 'the course Statistics page' does not explain identifier 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?

States a clear verb+resource: fetch data for a course's Statistics page. An agent can distinguish it from get_course_info or list_courses. However, 'the data' is vague about what statistics are actually returned, leaving the specifics unclear.

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 guidance on when to use this versus any sibling tool, nor any prerequisites. The note that instructors may hide the page hints at when a call might be futile, but it is framed as a caveat rather than usage routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds the read's content scope (answers, followups, replies), which is mild context, but it says nothing about pagination, truncation of long threads, or access requirements for private courses.

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 lines with the payload description front-loaded and the parameter hint second, no filler. The only wobble is the Piazza-specific 'both answers' phrasing, which presumes a domain convention rather than stating 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?

An output schema exists, so return structure need not be described, but with 0% schema coverage and an undocumented 'course' parameter, plus no differentiation from get_posts and get_post_history, the definition is only minimally complete for selecting the 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 0%, so the description must carry the load; it usefully explains that 'number' is the Piazza post number displayed as @123. However, 'course' is left entirely unexplained – no indication of whether it is a slug, numeric id, or network identifier – leaving one of two required parameters ambiguous.

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 ('Read one full thread') and enumerates the returned content: question/note, both answers, followups with replies. The singular 'one full thread' implicitly separates it from the plural siblings get_posts/list_posts, but it never explicitly names get_post_history or explains how it differs.

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, no prerequisites, and no alternatives named; the agent must infer that this is the single-post lookup chosen over list_posts or search_posts. The one hint given ('number is the post number that Piazza shows as @123') is parameter clarification, 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?

The diff=true semantics are materially useful behavior the annotations cannot express: version 1 carries full text, later versions only carry deltas. Ordering and included fields are also disclosed. Missing are error/edge behavior (nonexistent number, deleted posts) and volume limits, which matters given openWorldHint=true.

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, zero padding, and the core capability is front-loaded before the diff nuance. 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?

An output schema exists, so return values need not be re-explained, and the description still usefully previews shape (author, time, diffs). What is missing for a history/read tool is guidance on error cases and whether history is bounded or truncated.

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 the load and it only explains 'diff' — the one non-obvious parameter. 'course' and 'number' are left undefined; 'number' in particular is ambiguous (post number vs. version number) and is not clarified anywhere in the schema.

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

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

States a specific verb and resource ('Show every version of a post') plus the ordering ('oldest first') and payload ('author and time'), which implicitly distinguishes it from the single-version get_post. It never names a sibling explicitly, so sibling differentiation is left to inference.

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

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

'Use it to see what an instructor changed in an announcement or a question' gives a concrete triggering scenario, which is stronger than nothing. It stops short of contrasting with get_post/list_posts or stating when history is unnecessary, so no exclusions or alternatives are offered.

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 openWorldHint, so safety is covered. The description usefully adds the partial-failure contract ('A post that cannot be read has an "error" field') and the batch ceiling of 20, but says nothing about pagination, truncation when more than 20 numbers are supplied, or per-post error causes.

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-loaded with the core capability and immediately followed by the failure-mode note. Every clause carries information; nothing is redundant 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?

An output schema exists so return-shape detail is not required, and the description does add the error-field behavior on top of it. However, the batching edge case (what happens beyond 20 numbers, whether excess are dropped or rejected) and the identifier formats are unresolved for a two-required-parameter read tool.

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

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

Schema description coverage is 0% for both parameters, so the description must compensate. It partially does: 'one course' maps to the course parameter and 'up to 20 full threads' implies numbers is a bounded list of post identifiers, but the format of course (name vs ID) and the meaning/ordering of the integers are never stated.

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 ('Read'), resource ('full threads'), scope ('from one course') and batching behavior ('in one call', 'up to 20'). An agent can distinguish it from single-post readers like get_post, though no sibling is named explicitly, which is what separates this 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?

There is no explicit when-to-use guidance and no alternatives are named. The phrase 'in one call' hints that this is the batch variant versus a single-thread reader, but the selection rule (when to batch versus call get_post or search_posts) is left 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 cover readOnlyHint, idempotentHint and openWorldHint, yet the description adds genuinely non-derivable behavior: 'one request per course' (a cost/latency signal an agent should plan around) and the fact that zero-unread courses are omitted from the result. It does not, however, discuss auth requirements or the shape/ordering of the per-course result.

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 zero filler, and the core purpose is front-loaded before the request-cost and default-filtering details. Every sentence carries information the agent cannot get from the schema or annotations.

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

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

With an output schema present, return values need not be explained, and the annotations carry the safety profile, so the remaining burden is the default behavior and cost, both of which are covered. The main residual gap is the absence of any routing hint relative to the many sibling listing 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 single include_inactive parameter is undocumented in the schema; the description partially compensates by stating 'By default only active courses are counted,' which lets the agent infer that overriding the default includes inactive courses. It never names the parameter or states the explicit value needed, so compensation is only partial.

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 (count) and resource (posts with unread content, per course), which clearly separates it from retrieval siblings like get_posts or list_posts. However, it never names or contrasts itself with any sibling, so the agent must infer the distinction from the verb alone rather than being routed 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 purpose ('count unread content in each course' tells you to reach for this when you want an unread overview), but there is no explicit when-to-use, when-not-to-use, or alternative (e.g., use get_posts for the actual unread posts rather than counts).

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 openWorldHint, so safety is covered. The description adds real behavioral context beyond them: the default path is served without hitting Piazza, and refresh=true forces a reload from the remote source. It does not mention cache staleness windows or latency tradeoffs.

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 with no filler. The primary behavior and returned fields come first, followed by downstream usage and the optional flag, which is the right front-loading order.

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 listing tool with an output schema, the description covers purpose, returned content, identifier handoff to other tools, and refresh semantics. Only minor operational details (whether courses are paginated, how authoritative the cached list is) are absent.

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 optional parameter, but the description compensates by explaining that refresh=true triggers a reload from Piazza, which implies the default (false) serves cached data. That is the essential semantic an agent needs for the only parameter.

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

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

Specific verb ("List") plus a bounded resource ("the user's Piazza courses") and an enumeration of the fields returned (ID, course number, term, role, active status, post folders). It is clearly a bulk-listing tool rather than a per-course lookup, but it never names or contrasts with the closest sibling, get_course_info, so the differentiation is only implied.

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?

"Other tools accept the ID, the course number, or part of the name" effectively explains this tool's role as the identifier-discovery step, and "Set refresh=true to reload from Piazza" gives a concrete condition for using the option. No explicit when-not or named alternative is given, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds the useful ordering behavior ('most recent first'), which the annotations do not convey, but says nothing about pagination, result volume, or what the openWorld flag implies in practice.

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 front-loaded sentence with verb first, scope in the middle, and ordering last. No wasted words, though it is terse enough that parameter guidance is absent rather than merely compressed.

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-value explanation is not required and the annotations cover safety. However, for a tool with a required 'course' parameter and 0% schema coverage, the description leaves a real gap: an agent gets no guidance on supplying or formatting the required argument.

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% and the description does not mention either parameter. The required 'course' parameter — the one an agent must supply to call the tool at all — is completely undocumented, as is the 'limit' default of 20. The description only hints at the author-type scope, not how to scope a query.

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 (List) and resource (notes and polls written by instructors) and clarifies content scope with examples ('announcements and logistics'). It implicitly separates itself from generic siblings like list_posts/search_posts by restricting to instructor-authored content, but never names an alternative 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?

The phrase 'written by instructors' implies when this tool is appropriate versus general post tools, but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage is left to inference from the sibling set.

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 open-world behavior, so safety is covered. The description adds real context beyond them: results are ordered by recent activity, each summary carries only a short snippet, and full content requires a different call. It does not mention pagination behavior, though limit/offset exist.

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 one-line purpose before drilling into filter/folder semantics, then closes with the escalation pointer. Dense but every sentence does work; the filter block is a little list-like but not wasteful.

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 shape needn't be restated, yet the description usefully warns the summaries are snippet-only. With annotations covering safety, the only real omission is the meaning/defaults of limit and offset.

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 the load. It does well on filter (seven modes enumerated and explained, except the default "all") and folder (with an example), but says nothing about limit, offset, or course syntax. The remaining gaps cap it at a solid-but-incomplete 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?

States a specific verb and resource ("List post summaries for a course") plus scope and ordering ("most recent activity first"). It clearly distinguishes itself from siblings get_post/get_posts, which it says return "full threads" instead of summaries.

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 routes the agent: enumerates what each filter value selects, explains the folder constraint, tells the agent that list_courses reveals folder names, and names the alternatives (get_post/get_posts) for complete threads. The when-to-use boundary is unambiguous.

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, so safety is covered. The description adds two useful behaviors: the default window is 7d and courses with no activity are omitted. It says nothing about how limit truncates results or what include_inactive changes.

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 the core purpose, then the parameter detail and the use-case trigger. Compact with little waste, though the line-break layout is slightly choppy and the ordering of the 'courses without activity' note is a bit arbitrary.

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 need not be explained, and the purpose plus the `since` semantics are clear. However, half the input surface (limit, course, include_inactive) is unexplained, and the interaction between 'courses without activity are left out' and include_inactive is left for the agent to infer.

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% across 4 parameters, so the description carries the full burden. It documents only `since` (relative age format like 24h/7d/2w, or ISO date) and its default; `limit`, `course`, and `include_inactive` are left entirely undefined 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?

States a specific verb and resource with a qualifying scope: list posts with *new activity* since a time, across all active courses or one course. The 'new activity' qualifier meaningfully separates it from plain list_posts/get_posts, though the description never names those 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?

Gives a concrete usage trigger ('what did I miss this week'), which tells the agent the intended question shape. It stops short of naming alternatives (list_posts, get_post_history) or stating when this tool is the wrong choice.

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 openWorldHint, so the safety profile is covered. The description adds useful scope behavior (searches one course or all active courses by default) and states that results are post summaries grouped by course, but return shape overlaps with the existing output 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?

Two tight sentences: purpose and scope first, usage trigger immediately after, followed by the return granularity. No filler or restated name/title 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?

With an output schema handling return values and annotations handling safety, the description supplies the missing pieces: when to invoke, search scope, and result grouping. Only the undocumented 'limit' parameter remains a small gap.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies 'query' (keywords) and 'course' (single course vs. all active courses, matching the null default), but never mentions 'limit' or its pagination/result-count effect.

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 (search) plus resource (posts) and scopes it precisely: keyword matching, constrained to one course or all active courses. The 'like the Piazza search box' analogy and keyword framing cleanly separate it from sibling listers such as list_posts and get_posts.

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 a concrete trigger ('use it before the user asks a new question, to find duplicates'), which is real actionable guidance. It stops short of naming an explicit alternative or a when-not condition, but the intended situation is unambiguous.

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