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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write nature is covered. The description adds nothing about what happens on a name collision, whether duplicates are allowed, whether the call fails or overwrites, or what is returned (a folder id?) — meaningful gaps for an operation the annotations themselves flag as destructive.

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 front-loaded sentence with no filler. It is efficient, though the length means there is essentially no supporting 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?

For a one-parameter creation tool with no output schema, the description covers the what but not the outcome or failure modes. An agent still does not know what happens after creation or how to reference the new folder.

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

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

There is a single required parameter with 100% schema description coverage ('Name for the new MIO folder'), so the schema already carries the semantics. The description adds no constraints such as allowed characters, length, or uniqueness rules, leaving it at the baseline.

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

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

States a specific verb and resource: 'Create a new custom folder in MIO', with a clarifying gloss that MIO is internal messaging. This clearly separates it from the read-style siblings like get-mio-folders, though no sibling is named 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?

There is no guidance on when to create a folder versus using the default folders, no prerequisites, and no mention of the related siblings (move-mio-message, get-mio-folders) that would typically follow. Usage is only implied by the verb.

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

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

Annotations declare destructiveHint=true, but the description adds the crucial nuance that this is a soft delete into trash and therefore reversible, which materially changes an agent's risk calculus. It doesn't state retention/expiry of trashed items or whether batch deletes are atomic, 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 short sentences, zero waste, with the most decision-relevant fact (non-permanent) front-loaded and the recovery path 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?

For a single-parameter, no-output-schema tool with full schema coverage, the description supplies the reversibility guarantee and undo route that an agent needs before calling a destructive-annotated tool. Minor gap: nothing about partial failure when an array of IDs is passed.

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% — the schema already documents the UUID format, the single-or-array anyOf, and the source (get-mio-messages). The description adds nothing about parameter behavior, 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 ('Move ... to trash') and resource ('MIO message'), plus a scope qualifier ('not permanent'). It clearly separates itself from restore-mio-message and from move-mio-message (which relocates rather than trashes) without needing the schema.

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

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

Explicitly routes the agent to restore-mio-message as the undo path, which is the main decision an agent faces after deleting. It does not address adjacent choices such as flag-mio-message or move-mio-message (folder relocation), so it stops short of full when/when-not coverage.

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=false and destructiveHint=true, so the safety profile is provided structurally. The description adds no behavioral detail beyond naming the flags, such as whether both booleans are required to be supplied and whether setting them overwrites existing flag state.

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

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

The description is a single efficient sentence with no wasted words and front-loads the operation. It is appropriately sized for a simple flag-setting tool.

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

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

The schema fully documents the parameters and annotations provide the mutation safety profile, so the description is minimally sufficient. However, for a destructive flag-setting mutation, it omits important context such as the fact that both flags are required and that setting them may clear existing flags.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description mentions the two flag fields but adds no syntax, required-both behavior, or meaning beyond what the schema provides.

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

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

The description states a specific action ("Set flag indicators") on a specific resource ("MIO message") and names the two flags being changed. It distinguishes the operation from siblings like read-mio-message or delete-mio-message, though it does not explicitly contrast itself with those alternatives.

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

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

The description gives no guidance on when to use this tool versus alternatives such as move-mio-message, read-mio-message, or restore-mio-message. Usage is only implied by the tool name and the word "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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the useful behavioral detail that the default is the current term, but says nothing about output shape, per-course grouping, or what an 'absence summary' contains.

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

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

One sentence, front-loaded with the verb and resource, with the term scoping folded in efficiently. Nothing is redundant, though it is terse enough to leave gaps rather than over-explain.

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 optional-param read tool with no output schema, the essentials are present, but the agent still cannot tell what a returned 'absence summary' looks like or whether results are grouped per course. A brief note on the response structure would close the 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 coverage is 100% and already documents the YYYYN format for term_id. The description contributes beyond the schema by explaining the optional parameter's default behavior (current term when omitted), which the schema does not state because the field is not required.

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 (retrieve) and resource (absence summaries) with an explicit scope (all courses in a term). It is distinguishable from lookalike siblings such as get-cancelled-classes and get-course-evals, though it never names an alternative directly.

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

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

Implicitly tells the agent this is a per-term, all-courses fetch, and that omitting term_id falls back to the current term. There is no explicit when-to-use vs. when-not, and no mention of the neighboring tools an agent might confuse it with.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real interpretive context beyond them, namely the caveat that a file in the deposit means something was uploaded, not that the work is finished. That is exactly the kind of semantic warning an agent cannot infer from 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?

Two tight sentences with zero waste, front-loaded with the resource and its contents, and the chaining hint to get-assignment-file-link placed where it is actionable.

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 the return payload, and it does so by enumerating the returned sections plus the deposit caveat. It leaves minor gaps (no note on error cases or what happens when the deposit is empty), which keeps it from a 5.

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

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

Schema description coverage is 100%, so all three parameters (including term_id's YYYYN format and course_id's group-number requirement) are already documented in the schema. The description adds no parameter-level detail beyond schema; 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?

Specific verb+resource: full detail of a single assignment, with the returned contents enumerated (deadline, instructions, deposit contents, teacher documents, corrected copies). It is clearly distinguishable from get-course-assignments (listing) and get-assignment-file-link (which consumes the file IDs this tool returns).

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 makes the usage context clear: fetch this to obtain the file IDs that get-assignment-file-link requires, which explicitly routes the agent to the sibling. It does not state exclusions (e.g., when to prefer get-assignments-summary), so it stops short of a full when/when-not treatment.

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

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

Beyond the readOnly/non-destructive annotations, it discloses the dual-mode behavior: an expiring 15-minute browser link under HTTP mode with MCP_SERVER_URL, otherwise a locally saved file path. That is genuinely useful context for a tool whose output shape varies by environment, though it omits any auth/permission requirements.

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 waste: the first states purpose and scope, the second states the environment-dependent return behavior plus the input source. Front-loaded and appropriately sized.

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, yet the description explains what is returned in both modes (expiring link vs local path), and the schema covers parameter details. An agent has everything needed 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 description coverage is 80%, so the schema already documents role, file_id, course_id, and assignment_id including the "course_id always required" note. The description only adds provenance guidance (IDs from get-assignment-detail) and nothing about the optional term_id, so it sits at the baseline for high-coverage schemas.

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 ("Fetch an assignment file") and enumerates the three file kinds covered. It is clearly distinguishable from siblings like get-assignment-detail (metadata) and get-document-link (course documents).

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 tells the agent where to source inputs ("Get file IDs and roles from get-assignment-detail"), which implies the correct workflow order. It does not explicitly say when to prefer this over e.g. get-assignment-submit-link or get-document-link, so no exclusions are stated.

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

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

Annotations already cover read-only safety, and the description adds non-obvious behavioral context: it only counts assignments teachers posted on Lea, and an empty summary does not mean the student is caught up. It also indicates the return contains counts and pending titles. It doesn't detail output formatting or pagination, but for a summary read this is strong added context.

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

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

Three front-loaded sentences with zero waste: purpose first, then the key caveat, then the alternative routing. 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?

For a read-only summary with one fully documented parameter, no output schema, and annotations that cover safety, the description supplies everything needed: scope, caveat about empty results, and alternative tool guidance. Nothing material is missing.

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

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

There is one parameter and schema description coverage is 100%, with the pattern and format fully documented. The description only says 'for a term' and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

The description specifies the exact resource (per-course assignment counts for a term) plus the extra content (titles Lea still lists as to hand in), and explicitly distinguishes itself from get-course-assignments. An agent can identify the tool's output without opening the schema.

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

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

It names the sibling get-course-assignments and the condition that selects it (deadlines and deposit contents). The caveat about empty summaries further clarifies how to interpret results, leaving little 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?

Adds substantial context beyond annotations: the link is pre-authenticated, expires after 15 minutes, fails when online submission is closed, and fails when the server lacks a public URL. It also clarifies the important non-obvious behavior that the tool never submits files.

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 focused sentences, front-loaded with the core purpose, immediately followed by intended usage, then expiry and failure modes. No filler or redundancy.

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

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

Given an output schema and safety annotations already present, the description supplies the remaining operational context an agent needs: what the link is for, that it is not a submission action, expiration, and failure conditions. Nothing essential is missing.

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

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

Schema description coverage is 100%, so parameters are already well documented in the schema. The description adds no additional parameter-level guidance beyond what the schema provides, which is acceptable at 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?

States a specific verb and resource: get a short link that opens the Omnivox hand-in page for an assignment. It clearly distinguishes the tool from submission itself and from related file-download tools by framing it as a hand-in/upload link, not a file retrieval 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?

Explicitly says to give the link to the user so they can upload in their own browser, and clarifies the tool never submits anything itself. It also states failure conditions. However, it does not explicitly route against siblings like get-assignment-file-link or get-assignment-detail beyond the hand-in framing.

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

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

The annotations already declare this is a safe read-only operation, and the description adds useful behavioral context about data completeness: exam and assignment dates depend on teacher entry and the syllabus should be consulted for the full picture. It does not explain pagination or how the page parameter affects results, which keeps it from a 5.

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

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

The purpose is front-loaded in the first sentence, followed by the sibling comparison and then the data completeness caveat. All three sentences carry useful information with no redundant restatement of the title.

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?

The description explains the calendar contents and the major data limitation, which is helpful for a tool with no output schema. However, it omits parameter behavior for page and range, so an agent still lacks guidance on how to control the returned time window or pagination.

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 of explaining the two parameters. It does not explain what 'page' controls or clarify the meaning of the 'range' enum values, leaving parameter usage largely inferential.

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 gives a specific verb and resource: retrieve the day-by-day calendar. It enumerates the relevant contents (classes, holidays, day swaps, cancelled classes, exams, deadlines) and explicitly distinguishes the tool from get-schedule for day-specific information.

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 says to prefer this over get-schedule for what happens on a given day, which gives a clear routing rule. It also warns that exam and assignment dates only appear if the teacher entered them on Lea, so the agent knows the tool may not be complete.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that teacher comments are included in results, but it does not define the 'upcoming' window (how far ahead, whether past cancellations are excluded) or ordering, which are the behaviors that actually matter for this read.

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 front-loaded sentence that packs the resource scope and the returned fields with zero filler. Nothing to trim and nothing important 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?

For a no-parameter read tool with no output schema, describing the returned fields is exactly the right compensation, so an agent knows what it gets back. The one missing piece is the definition of the 'upcoming' time horizon, which affects whether the results meet the caller's need.

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; baseline 4 applies. The description's field list reinforces that the output is self-contained with no filtering inputs.

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

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

The description uses a specific verb (Retrieve) plus a clearly scoped resource (upcoming cancelled class sessions) and even enumerates the returned fields (time, course, teacher, room, comment). It is clearly distinguishable from siblings like get-schedule or get-calendar, though it never names those siblings explicitly.

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

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

Usage is implied by the word 'cancelled' – an agent can infer this is the tool to call when checking for cancelled sessions – but there is no explicit when-to-use, when-not-to-use, or pointer to get-schedule/get-calendar for the non-cancelled case.

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

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

Goes well beyond the readOnlyHint/destructiveHint=false annotations: it explains that an unopened mandatory document blocks every Lea tool, that opening must happen in Omnivox by the student, and that opening is recorded on the student file. That audit/permission consequence is exactly the context annotations cannot express.

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 what is returned, then the read-only constraint and its consequence, then the invocation trigger. Every sentence carries new information — no restatement of the title or the 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 no parameters, no output schema, and annotations already covering the safety profile, the remaining burden is scope and consequence — both are covered (document categories, the blocking behavior, the fact that it returns names only). An agent can call this correctly without further information.

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 the baseline of 4 applies; there is nothing for the description to disambiguate in the input schema. The description correctly focuses its words on scope and consequences instead of inventing parameter detail.

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 the official documents the college has sent to the student') and enumerates the document types (admission letters, enrollment confirmations, notices, acknowledgments). It distinguishes itself from get-course-documents only implicitly via 'the college has sent' vs a course context; naming that sibling explicitly would remove the last ambiguity.

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 when another tool reports a mandatory college document block.' It also implies the when-not — this tool only names the document, so opening requires the student to act in Omnivox (or a link tool). No explicit alternative is named for opening, which keeps it short of a 5.

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 indicate this is a read-only, non-destructive operation. The description adds useful scoping by saying the list is 'available to the user,' but it does not disclose other behavioral details such as ordering, filtering, or whether results depend on enrollment/application state.

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

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

It is a single tightly written sentence with no wasted words, and the core action is front-loaded.

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

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

For a zero-parameter read tool with annotations and an output schema, the description is nearly sufficient. A little more scope detail about which colleges are included and how this differs from sibling college tools would make it 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?

The tool has zero parameters, so the baseline is 4. There are no parameter semantics for the description to compensate for.

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 gives a specific verb-resource pair, 'Retrieve the list of colleges,' and clarifies that the list is scoped to the user. It is clear but does not distinguish this tool from nearby siblings like get-college-documents or get-college-news.

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 states what the tool retrieves but gives no explicit guidance on when to use it instead of alternative college-related tools. Usage is only implied by the resource name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results are 'latest,' implying recency ordering, but says nothing about result count, pagination, or whether content is cached/dated.

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 front-loaded sentence with no filler; appropriately sized for a simple zero-argument read. Slightly thin given the ambiguity with a sibling tool, but no wasted text.

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

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

For a zero-param read with annotations covering safety and no output schema, the description is adequate but incomplete: it doesn't clarify what 'news' includes, whether course announcements are separate, or expected volume/format of 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?

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description correctly implies the tool is called with no filters.

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?

Clearly states a specific verb+resource (retrieve college news and announcements), so an agent knows what it fetches. However, it never distinguishes itself from the sibling get-course-announcements, leaving the college-wide vs course-level scope ambiguous.

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

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

The description gives no guidance on when to use this versus get-course-announcements, get-college-documents, or get-overview. There are no exclusions or prerequisites, only a bare statement of what it returns.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the retrieval scope and does not disclose any further behavior such as permissions, pagination, or return characteristics.

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

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

The description is a single front-loaded sentence with no wasted words. It is structurally clean, though very terse.

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 tool with full schema coverage and safety annotations, the description is minimally adequate. However, it lacks usage guidance and does not describe what the announcements response contains, which matters because there is no output schema.

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

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

Schema description coverage is 100%, so both course_id and term_id are already documented in the schema. The description adds no parameter-level meaning beyond the schema baseline.

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

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

The description states a specific verb and resource: retrieving announcements for a specific course. It is clear what the tool does, but it does not distinguish itself from nearby siblings such as get-college-news or get-mio-messages.

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

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

The description gives no indication of when to use this tool versus alternatives, nor any exclusions. The 'specific course' scope is implied, but there is no explicit routing guidance despite many sibling tools.

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

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

Beyond the readOnly/destructive annotations, the description discloses real behavioral traits: deposit presence means an upload occurred, not completion, and the source is known to be sparsely populated. This is meaningful caveat context an agent could not infer. Minor gap: no mention of ordering, pagination, or depth of the deposit listing.

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, each carrying distinct information, with the core action stated first. Slightly dense in phrasing ('what is in the hand-in deposit') but no filler.

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

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

For a two-parameter read-only list tool with a fully documented schema and safety annotations, the description covers purpose, output content, known data-quality limitations, and a fallback source. An agent has everything needed to call it and interpret an empty response correctly.

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

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

Schema coverage is 100% and both parameters are fully documented in the schema, including the term format and the note that course_id is always required. The description adds no parameter-level detail beyond this, 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 uses a specific verb and resource ('List the assignments of a course') and names the concrete fields returned (deadline, hand-in deposit contents). It does not, however, differentiate itself from the closely related siblings get-assignment-detail and get-assignments-summary, 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?

It gives clear situational guidance: the list is 'incomplete by nature' and an empty result does not mean no homework, and it routes the agent to get-course-documents for the authoritative syllabus. It stops short of saying when to prefer this over get-assignment-detail or get-assignments-summary.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: no pagination behavior, no mention of what metadata each document entry carries, no note on empty-course 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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity is partly under-specification rather than tightness.

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 two-parameter read tool with full schema coverage and annotations, the essentials are present. The missing piece is routing context against the many sibling document/course tools, which matters given this tool list's density.

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 course_id's schema text already explains the full-ID format and that it is always required. The description's phrase 'for a specific course' merely restates the required parameter, so baseline 3 applies.

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

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

States a specific verb (retrieve) and resource (documents for a course), so the operation is unambiguous. It does not, however, distinguish itself from siblings such as get-college-documents or get-document-link, which an agent could easily confuse it with.

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 choose this over get-college-documents (the college-level counterpart) or get-document-link (which fetches an actual file). The description gives no exclusions, prerequisites, or selection criteria.

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 establish that this is a safe read-only operation, and the description adds valuable behavioral context: ungraded evaluations show no mark, and evaluations not entered in Lea will be absent entirely. That helps an agent interpret incomplete results, though it does not cover permissions, rate limits, or return structure.

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 front-loaded with the purpose, then two short sentences add distinct caveats and a reconciliation action. Every sentence earns its place without repetition or bloated setup.

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

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

For a read-only tool with complete schema coverage and no output schema, the description gives enough to understand what is returned and the major data-completeness caveats. It could be slightly stronger with a hint about the shape or grouping of returned evaluations and grades, but it is broadly complete.

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

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

Schema description coverage is 100%, with both term_id and course_id documented in the schema, so parameter meaning is already well covered. The description reinforces that the course is specific but adds no format or syntactic detail beyond the schema.

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

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

The description states a specific verb and resource set: retrieve evaluations, grades, and course summary for a specific course. It is clear what the tool does, but it does not differentiate itself from the similar sibling get-grades-summary or clarify its relationship to get-course-info.

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 focus on a specific course, and the description usefully warns to reconcile against the syllabus. However, it gives no explicit when-to-use guidance versus alternatives such as get-grades-summary or get-course-assignments.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and an output schema exists, so the safety profile and return shape are covered elsewhere. The description adds only that the payload includes identity and teacher names — useful, but no auth, caching, or error 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?

Two short sentences, front-loaded with the action and then the payload contents. No wasted words, though nothing is stated about term scoping despite an optional term_id.

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 readOnly annotations, a full output schema, and 100% schema description coverage, most of the burden is carried by structured fields. The description is complete enough to call correctly, though it omits how the optional term_id affects which offering is resolved.

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 course_id description already explains the group-number format and the 'always required' caveat. The description adds nothing about either parameter, 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 ('Retrieve') and resource ('info about a specific course') and names what is returned (course identity, teacher names). It is clear on its own, but it never distinguishes itself from close siblings like get-courses-summary, get-course-people, or get-teachers.

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-courses-summary (listing courses) or get-course-people / get-teachers (which also surface teacher data). The agent must infer the selection criteria from sibling names alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the bar is lower. The description still adds real value by disclosing the 75-result cap (a meaningful limitation) and describing the return payload (recipient IDs), which annotations do not cover.

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

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

Two tight sentences, front-loaded with what is returned and the result cap. Every clause adds information; 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?

A one-parameter read tool whose safety profile is covered by annotations and whose output is described (recipient IDs) despite no output schema. The result limit is surfaced, leaving nothing an agent needs missing before calling it.

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

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

Schema description coverage is 100% and the single course_id parameter is fully documented in the schema, so the baseline of 3 applies. The description adds no format or scoping detail beyond what the schema already provides.

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

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

States a specific verb ('List') and a scoped resource ('teachers and students for a specific course'), which implicitly distinguishes it from get-teachers (all teachers) and search-people. However, it never names those siblings, so the differentiation is inferred rather than stated.

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 'Returns recipient IDs usable with send-mio-message' gives a clear downstream usage cue. But there is no explicit when-to-use/when-not guidance, and no routing to alternatives like get-teachers or search-people for the same people data.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the default-to-current-term behavior, but says nothing about what the summary contains or its shape.

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

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

A single efficient sentence with no filler. Slightly under-specified rather than verbose.

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

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

With no output schema, the description carries the burden of explaining what a 'summary of courses' includes (which fields, per-course aggregates?), and it does not. An agent cannot anticipate the return value.

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 term_id pattern/format is fully documented in the schema. The description only adds that the term may be omitted in favor of the current term, which is a modest but real contribution.

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 (Retrieve) and resource (summary of courses), scoped to a term. It does not differentiate itself from nearby siblings like get-overview or get-course-info, and 'summary' is left undefined.

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 'for a given term or the current term' implicitly tells the agent the parameter is optional and that omitting it defaults to the current term. However, no explicit when-to-use guidance or named alternatives are given.

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

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

The annotations declare readOnlyHint=true, but the description says the tool marks the document as read on Omnivox and may save a file locally. Both are side effects that contradict the read-only annotation. Although the description usefully discloses expiry and return behavior, the contradiction is serious enough to score 1.

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

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

The description is three tight sentences with no filler. It front-loads the core action and then adds the return-mode behavior and the read-marking caution in a logical 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?

With no output schema, the description does a good job explaining both return forms and the 15-minute expiry. It also discloses the important side effect of marking the document as read. However, it leaves parameter semantics under-explained and does not resolve the read-only annotation conflict.

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 description provides no parameter guidance beyond the word 'document'. Schema coverage is only 67%, and document_id has no schema description at all, so the description should compensate but does not. The moderate schema coverage keeps this above the absolute minimum, but only barely.

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

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

The description states a specific verb and resource: fetching a Lea document. It also explains the two return modes (browser link vs. local path), which clarifies the tool's purpose. It does not fully distinguish itself from all related document/file-link siblings, though it names get-course-documents as the browsing alternative.

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

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

The description explicitly says to use get-course-documents first when only browsing, because this tool marks the document as read. That is a clear usage condition and alternative. It does not cover other sibling tools such as get-assignment-file-link or get-mio-attachment-link, but the guidance for the main ambiguous case is present.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results are limited to the user's courses, but it does not describe return shape, permissions, or whether the grades are official or provisional.

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 definition is a single, front-loaded sentence with no wasted wording. It communicates the action, resource, scope, and term behavior efficiently.

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 tool with one optional parameter and no output schema, the description gives enough context to invoke it correctly. It could be slightly more complete by describing the returned summary structure, but the essential scope and default-term behavior are present.

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

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

Schema coverage is 100% and the schema itself documents the term_id pattern and format. The description adds useful semantic behavior beyond the schema by clarifying that omitting the term uses the current term.

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

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

The description uses a specific verb, 'Retrieve,' and names the resource, 'grades summaries,' scoped to the user's courses. It is clear what the tool returns, though it does not explicitly distinguish itself from sibling summary tools such as get-assignments-summary or get-courses-summary.

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 indicates that a term can be supplied or the current term is used by default, which gives basic usage context. However, it does not say when to choose this tool over siblings or when not to use it.

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?

Goes well beyond the readOnly/non-destructive annotations by disclosing two distinct runtime behaviors: in HTTP mode a browser link that expires after 15 minutes, otherwise a local file is written and its path returned. The local-write side effect is important for an agent to know. Minor gap: no indication of where files are saved or what happens on invalid IDs.

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: the primary action and the dual-mode return behavior come first, the prerequisite pointer last. No 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?

With no output schema, the description correctly compensates by describing both possible return values (expiring link vs. local path). Complete enough to call correctly; only error/failure behavior is left implicit.

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

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

Schema coverage is 100% and both parameters carry descriptions, including the origin of attachment_id. The description adds no parameter-level detail beyond the pointer to read-mio-message, so baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a MIO message attachment') and immediately disambiguates from the sibling read-mio-message by declaring that tool as the source of attachment IDs. An agent can distinguish it from get-document-link / get-assignment-file-link by the MIO attachment scope.

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 clear prerequisite path: get attachment IDs from read-mio-message, which is the natural gateway. It does not explicitly say when to prefer this over get-document-link or get-service-link, but the resource scoping makes the choice reasonably inferred.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds real value beyond that: it explains the contents of each entry (unread counts) and documents the folder ID constant format such as SEARCH_FOLDER_MioRecu. It does not mention ordering or whether folders are flat vs nested, so it is not exhaustive.

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 purpose is front-loaded and the follow-on guidance about ID usage comes second, matching the natural call 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?

With no parameters, no output schema, and annotations covering safety, the description supplies enough to call it and to interpret the result (folders plus unread counts). A minor gap is that it doesn't state whether folders are ordered or can be nested, but nothing critical to invoking it is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description goes beyond the schema by pre-explaining the folder_id string constant format for downstream calls, which is useful even though this tool has no inputs of its own.

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 ('Retrieve the list of MIO folders') plus what each item carries (unread counts). The folder resource is clearly distinct from sibling tools like get-mio-messages, create-mio-folder, and move-mio-message.

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 second sentence tells the agent how the returned folder IDs are consumed by other MIO tools, which implies this is the discovery step before calling get-mio-messages. However, it never states when to use this versus alternatives or any exclusions, leaving usage largely inferred.

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

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

Annotations already establish that this is a read-only, non-destructive tool, so the description does not need to carry the full safety burden. It adds the pagination behavior, but does not disclose ordering, default folder behavior, or what kind of message data is returned.

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

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

The description is two short sentences, front-loads the core purpose, and adds the pagination detail without filler. Every sentence contributes something usable.

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

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

For a low-complexity read-only list tool with fully described parameters and safety annotations, the description covers the essential purpose and pagination behavior. It could be stronger by distinguishing itself from search-mio-messages and read-mio-message, but nothing critical for invoking it is missing.

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

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

Schema coverage is 100%, and the schema already documents count limits, last_id pagination semantics, and folder_id constants with a pointer to get-mio-folders. The description mentions pagination via last_id but adds no meaning beyond the schema.

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

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

The description states a specific verb and resource: retrieve MIO messages from a folder. That is clear and distinct from mutation tools like move-mio-message or delete-mio-message, but it does not differentiate this folder-listing tool from search-mio-messages or read-mio-message.

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

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

The description gives no explicit guidance on when to use this tool versus search-mio-messages or read-mio-message. 'From a folder' and pagination imply browsing folder contents, but the agent is left to infer that usage rather than being told directly.

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 establish readOnly/destructive=false, so the bar is lower, and the description still adds real context: the result includes a per-form open/closed status, and the tool cannot submit a form — that action remains in the Omnivox portal. It does not describe volume, ordering, or pagination, but for a small fixed list this is minor.

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

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

Two sentences with no waste; the resource and scope come first, and the read-only boundary follows as a second, distinct point. Every clause earns its place.

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

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

For a zero-parameter list tool with no output schema, an agent needs to know what is listed, what fields come back (open status), and that it cannot act on a form — all three are covered. Nothing required for correct invocation is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level gaps exist.

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 (the online forms the college publishes in Omnivox), and enumerates the form categories covered (workshop registrations, course withdrawal requests, surveys, sign-ups), which distinguishes it from document-oriented siblings like get-college-documents. It also names the per-item field returned (whether each is currently open).

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?

"Read-only: filling a form stays in the Omnivox web portal" clearly excludes the submission use case and redirects the agent elsewhere, which is the key boundary for this tool. It implies the correct use case (discovering available forms and their open/closed state) but does not explicitly name a sibling alternative or state exclusions relative to get-college-documents or get-service-link.

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 readOnly and non-destructive annotations already cover the safety profile. The description adds useful behavioral context by explaining that it aggregates multiple current actionable sections and uses delta tracking, though it does not mention freshness, caching, or whether sections may be empty.

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, front-loaded with the dashboard purpose and content scope, followed by a concise usage recommendation. There is no redundant or filler text.

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

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

For a composite dashboard tool with no output schema, the description does a good job listing the returned sections and framing it as a starting point. It leaves minor gaps around how the optional term_id affects the dashboard and whether some sections may be 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?

The sole optional term_id parameter is fully documented in the schema, including its YYYYN format and example. The description does not mention term_id or explain the default term behavior, so it adds no meaning beyond the schema here.

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

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

The description clearly states this is an aggregate dashboard and enumerates the specific content it surfaces: schedule, per-course new items with deltas, MIO messages, evals, notifications, and college news. This distinguishes it from the many granular sibling tools like get-schedule or get-mio-messages.

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

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

It gives a clear usage recommendation: 'Best starting point to see what needs attention.' However, it does not explicitly name when not to use it or route to specific sibling tools for narrower needs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely useful behavior beyond that: the data is static week-over-week and deliberately ignores holidays, day swaps and cancellations. It doesn't discuss return shape or ordering, but with a simple read this is a strong disclosure.

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

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

Three short sentences, front-loaded with what it returns, followed by the key caveat and the routing hint. No filler and nothing repeated from the 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 single-optional-parameter read tool with annotations and full schema coverage, the description covers purpose, default behavior, data freshness caveats and the alternative tool. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the parameter's format is already documented in the schema. The description nonetheless adds meaning the schema does not: the term is optional and falls back to the current term, which an agent needs to know to call it correctly.

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 ("Retrieve the static weekly class schedule/timetable") plus scope ("for a given term or the current term"). It explicitly distinguishes itself from the sibling get-calendar, so an agent can choose 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?

Names the alternative tool explicitly ("Use get-calendar for those") and gives the condition that selects it — holidays, day swaps, cancelled classes. It also states the default behavior when no term is supplied, which covers the main selection question for this tool.

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

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

Annotations only declare read-only/non-destructive/non-idempotent; the description adds the traits that actually matter here - the link logs the browser into the user's full Omnivox account, must be treated like a password, expires in 15 minutes, and any action taken on the page needs the user's explicit authorization. That is exactly the abuse and lifetime context an agent cannot infer from the 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?

Five short sentences, front-loaded with what the tool returns and why, followed by usage, then the security and expiry warnings. No sentence is redundant and the most consequential warning sits early.

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, the description need not explain return shape; it covers the remaining unknowns (account-level login scope, 15-minute expiry, authorization requirement) that determine whether the agent handles the result safely and 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 a fully documented enum, so the schema carries parameter meaning. The description still adds the framing that the chosen service is web-only and unreachable otherwise, which raises it slightly above the baseline.

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

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

States a specific verb and resource (get a pre-authenticated link to an Omnivox web-only service) and enumerates examples: lockers, transcript, progression chart, advisor appointments. The clause 'these services have no API here' separates it cleanly from the API-backed siblings such as get-grades-summary or get-schedule without needing to name them.

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 operating instructions: open the link yourself to read the page for the user, or hand it to the user, and require explicit per-action authorization before doing anything on the page. The when-to-use criterion (services that lack an API) is clear, though it never names the specific sibling link tools (get-document-link, get-assignment-submit-link) an agent might confuse it with.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral context: the fallback role and the deliberately omitted course-teacher association, which prevents misuse. It stops short of saying anything about the response shape beyond the field list, but the output schema covers 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?

Three tight sentences: purpose, payload contents, then the routing rule, with the most decision-relevant constraint placed early. No filler, though the fallback framing is restated slightly in the first and last sentence.

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

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

For a single-parameter read tool with annotations covering safety and an output schema covering return values, the description supplies everything an agent needs to decide whether to call it: what it returns, what it omits, and which sibling should be tried first.

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 term_id parameter is fully documented with a pattern and example in the schema. The description only implies term scoping via 'for a term', so it adds no syntax or format detail beyond what the schema already provides — baseline 3.

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

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

The description states a specific verb and resource ('get all teachers for a term'), enumerates the returned fields, and explicitly excludes course-teacher mapping. It is unmistakable against the sibling get-course-people.

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 names the preferred alternative (get-course-people) and gives the exact conditions for falling back ('only if get-course-people fails or you need the full roster'). When-to-use and when-not-to-use are both explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered structurally. The description still adds real behavioral detail the annotations lack: the response includes both the full list and the current default term, and names are human-readable rather than raw codes.

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 sentence, front-loaded with the verb and resource, with the return scope appended as a qualifier. Nothing is padded or repeated from the 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?

There is no output schema, so the description must carry the return-value story, and it does at a high level: term list plus current default, human-readable names. It stops short of saying what fields each term carries (id, name, date range), which would fully close the 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?

Zero parameters, so the baseline of 4 applies. There is no input to mis-specify and nothing the description could usefully add about argument semantics.

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 gives a specific verb (get) and resource (academic terms/sessions), and scopes the return as both the list and the current default term. No sibling tool in the list covers terms, so there is no ambiguity to resolve, though it never explicitly positions itself against anything.

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 only implied: an agent can infer this is the lookup for term identifiers, but the description never says so, nor does it mention that these term IDs feed other calls or that the default term is what to assume when unspecified. No alternatives exist to disambiguate against, which keeps this at minimum-viable rather than failing.

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=false and destructiveHint=true, so the safety profile is covered. The description adds no behavioral context such as source-folder removal, overwrite behavior, required permissions, or error handling; it restates the move action without contradicting the annotations.

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

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

The description is a single front-loaded sentence with no wasted words. For a simple two-parameter move operation, the length is appropriate and efficient.

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

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

The tool is low-complexity with a fully described schema and destructive annotation coverage, which carries much of the context. However, the description omits usage routing versus delete/restore/flag and does not explain move semantics beyond the one-line purpose, leaving meaningful gaps.

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 folder_id description already explains target folder constants and points to get-mio-folders for discovery. The description adds no syntax or constraints beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Move') and resource ('MIO message') and names the destination concept ('different folder'). It is clear but does not explicitly differentiate from related siblings such as delete-mio-message, restore-mio-message, or flag-mio-message.

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 mention of alternatives. Sibling tools like delete-mio-message, restore-mio-message, and flag-mio-message overlap in the MIO-message domain, but the description does not route the agent among them.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered, and the description usefully adds the return format ('complete message body as plain text') in the absence of an output schema. However, it never mentions the mark_read side effect (a read receipt sent to the sender) or behavior for unknown/inaccessible message IDs, which is the one genuinely non-obvious trait of this tool.

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 padding, with the identity of the resource front-loaded and the return format appended as the last piece of information an agent needs.

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 two-parameter read tool with full schema coverage and no output schema, the description covers what it does, the scope ('any folder') and the return shape. The only material gap is the undisclosed read-receipt side effect of mark_read, which the description leaves entirely to the schema.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description only echoes that lookup is by message ID. It adds no meaning beyond the schema and says nothing about mark_read, but with full schema coverage the baseline of 3 is appropriate.

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

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

States a specific verb (retrieve/read), a specific resource (a single MIO message by ID) and a scope qualifier ('from any folder') that distinguishes it from the list-oriented siblings get-mio-messages and search-mio-messages. It stops short of naming those siblings explicitly, so an agent must infer the split from context.

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 'single ... by its ID' versus the plural/query siblings, but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent can infer it is the follow-up to a list/search call, but the description does not say so.

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 cover the safety profile (readOnlyHint=false, destructiveHint=true), and the description adds real context beyond them: the reply is addressed to the original sender, the original is quoted underneath, and the thread is linked. It does not clarify that the send is irreversible or what happens on failure, which keeps it from 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 short sentences with zero filler, and the core action is front-loaded before the behavioral details.

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 5-parameter mutation tool with full schema coverage and annotations, the description covers what the agent needs to invoke it correctly. The only omission is what the call returns (e.g., the created reply's id), and there is no output schema to compensate.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description only echoes the default quoting behavior and recipient targeting, adding no syntax or format detail beyond the structured fields.

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

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

States a specific verb+resource ('Reply to a MIO message') and the delivery behavior (sends to original sender, quotes, links thread). It is meaningfully distinct from the sibling send-mio-message, though it never names that sibling 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 only implied — an agent can infer this is for responding to an existing message rather than composing a new one. There is no explicit when-to-use/when-not guidance or reference to send-mio-message or reply_all alternatives.

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=false and destructiveHint=false, so the safety profile is covered. The description adds the trash→inbox state change, but omits notable behavior the schema allows: bulk restore of an array of IDs, and what happens if the message isn't in trash.

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 front-loaded sentence with zero filler that conveys verb, resource, and state transition. Nothing 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 one-param tool with full schema coverage and annotations present, the description is essentially complete. The only minor gap is not surfacing the bulk/array restore capability in prose.

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% – the schema documents message_id fully, including the UUID format, the source tool (get-mio-messages), and single-or-array usage. The description adds nothing beyond the schema, so baseline 3 applies.

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

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

States a specific verb (restore) and resource (MIO message), plus the state transition from trash to inbox. This clearly distinguishes it from delete-mio-message and move-mio-message, though it doesn't reference those siblings by name.

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

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

'From trash back to the inbox' implies the precondition that the message must be deleted, which is useful context. However, no explicit when-to-use vs. alternatives (move-mio-message, delete-mio-message) is given, leaving the agent to infer the 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=true and destructiveHint=false, so safety is covered. The description adds nothing beyond that: no matching semantics (substring vs full-text), case sensitivity, result cap, or pagination behavior — all of which matter for a search tool with no 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?

One short, front-loaded sentence with no redundancy. It is efficient, though the terseness means there is little substance behind the lead clause.

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

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

With two fully documented parameters and read-only annotations, the definition is callable as-is. But with no output schema, the description should say something about what comes back (message summaries, match count, ordering), and it does not.

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

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

Schema coverage is 100%, and the schema already explains query and folder_id, including the get-mio-folders discovery hint and the all-folders default. The description itself contributes no parameter detail, so the baseline 3 applies.

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

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

The description states a specific verb and resource ("Search MIO messages") plus the matching dimension ("by text"), which clearly distinguishes it from mutation siblings like delete-mio-message. It stops short of naming the nearest alternative, get-mio-messages, so an agent must infer search-vs-list from the verb alone.

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 use this tool rather than get-mio-messages, read-mio-message, or search-people. The only usage signal is the word "search", leaving the choice between listing and searching to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the bar is lower here. The description adds the downstream purpose (recipient IDs for MIO) but says nothing about result volume, partial-match behavior, or whether searching is case/accent sensitive.

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 waste, with the primary purpose front-loaded and the use case following. Nothing to trim.

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 cover safety. For a one-parameter read tool the definition is nearly sufficient; only the lack of routing guidance versus sibling people-lookup tools is a real gap.

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

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

With a single parameter and 100% schema description coverage, the schema already documents 'Name or partial name to search for'. The description only restates 'by name' and adds no matching-prefix or minimum-length guidance, so baseline 3 applies.

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

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

States a specific verb and resource ('Search for people') and enumerates the entity types covered (students, teachers, employees), which is more precise than the title alone. It does not explicitly distinguish itself from siblings like get-teachers or get-course-people, so an agent must infer that this is the cross-directory name lookup.

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 one concrete use case: finding recipient IDs for send-mio-message, which is genuinely helpful context. It offers no exclusions or alternatives (e.g. use get-course-people for a roster within a course), so when-not-to-use is left to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation/irreversibility signal is covered structurally. The description adds the prerequisite lookup and the multi-recipient capability, but says nothing about whether the message is delivered immediately, whether a draft state exists, or how failures for some recipients in a batch are reported — useful context for a send operation.

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, purpose front-loaded, prerequisite second. The final sentence about multiple recipients is somewhat redundant with the recipient_id schema description, which keeps it from a 5.

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

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

For a 4-parameter mutation with full schema coverage and no output schema, the description covers what to send and how to obtain the required ID. The main omission is outcome behavior — delivery timing and partial-failure handling for multi-recipient sends.

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 each parameter is documented there, including the single-vs-array recipient form and the BCC-like hide_recipients flag. The description's mention of multiple recipients largely restates the schema, so it adds little beyond baseline.

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

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

Specific verb+resource ('Send a new MIO message') that cleanly distinguishes it from sibling mutations like reply-mio-message, move-mio-message, and delete-mio-message. It does not explicitly name those siblings, but the word 'new' does the disambiguating work.

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 prerequisite workflow: look up recipient_id via search-people first. It stops short of stating when not to use it (e.g., use reply-mio-message to respond within an existing thread), so an agent must infer the exclusion from the sibling names.

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