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

Goes beyond the annotations (destructiveHint=true, openWorldHint=true) by disclosing the key safety behavior: existing files are not overwritten unless overwrite=true, plus a named error condition (FeatureDisabled). Does not cover auth/permission requirements or what a successful result 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?

Front-loaded with the action and resource, then constraints and failure mode in tight prose with no filler. Well organized into three focused sentences.

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 download tool with no output schema and annotations covering the safety profile, the description supplies the essential non-overwrite default, directory constraint, and error condition. The unexplained 'district' parameter and absence of auth details are the main residual 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 coverage is 50%; documentId and destinationPath are already documented in the schema and the description largely restates them. It does add the semantics of overwrite (schema has no description for it), but the required 'district' parameter remains unexplained in both schema and description.

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

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

Names a specific verb (Download) and resource (a student's document/PDF) and states the destination scope (inside IC_DOWNLOAD_DIR). It is clearly distinguishable from the sibling ic_list_documents, which enumerates rather than retrieves.

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?

Provides workflow routing by identifying documentId as the url field produced by ic_list_documents, and notes the module can be disabled (FeatureDisabled). It gives a clear precondition but no explicit exclusions or alternatives beyond that.

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/openWorld annotations, it discloses substantial behavior: the features object is a map of ~90 named flags to booleans, that false means disabled while true/missing means available, and that a failed fetch yields an `error` field instead of `features`. This is exactly the value-add the annotations do not provide.

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

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

Purpose is front-loaded, and every subsequent sentence earns its place by explaining flag vocabulary, boolean semantics, and error handling. 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?

With no output schema, the description fully carries the burden of describing the return shape (features map, error alternative) and the meaning of values. 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 coverage is 67%, and the description adds no parameter-level meaning: it never explains `view`, `district`, or how `studentId` maps beyond the schema's own note. The structured schema already documents view and studentId, so this sits 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?

The description names a specific verb (List) and a precise resource (the district's displayOptions feature-flag allow-list) scoped per enrollment of a named student. This clearly differentiates it from the sibling list/get tools covering schedules, grades, attendance, etc.

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 explains the intended use case: 'exposed here so the LLM can answer capability questions directly,' and notes it is used internally to short-circuit disabled features. That gives clear context for when to reach for it, though it stops short of naming an alternative when capability info is not needed.

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 annotations by disclosing the non-obvious side effect that fetching may mark the message as read in the portal, which is precisely why readOnlyHint is false — the agent is told this is not a pure read. It also flags the returned text as third-party untrusted data that must never be followed as instructions, a critical safety trait for an openWorld fetch.

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 sentences, front-loaded with the verb and return shape, and each subsequent sentence carries load (URL provenance, path forms, read-marking side effect, untrusted-content warning). Minor redundancy: the accepted URL forms are restated from the schema's own parameter description.

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 spells out the parsed return shape, and it covers the side-effect and trust concerns an agent needs before invoking an open-world fetch. Only the `view`/`district` parameters and error behavior are left 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 coverage is 67%, so the schema already documents all three parameters. The description reinforces `messageUrl` by explaining its provenance (the `url` field of an ic_list_messages inbox item) and accepted path forms, but says nothing about the `view` enum or what `district` means, so it does not fully compensate for the coverage gap.

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

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

States a specific verb+resource (fetch/parse the HTML body of an inbox message) and names the exact return shape { subject, date, body, url }. The reference to ic_list_messages' inbox section cleanly separates it from the list sibling that only enumerates 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?

Explicitly tells the agent to obtain `messageUrl` from an item returned by ic_list_messages' inbox section, which is a real routing rule, and clarifies that both relative and /campus/-prefixed forms work. It gives no negative guidance, however — e.g. it never says to use ic_download_document for attachments or what to do if the item has no url field.

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 and openWorldHint, and the description adds genuinely non-obvious behavior: no date/term filtering is applied and each placement carries its own term. It doesn't discuss pagination or result size, but the unfiltered-scope disclosure is the key behavioral trait here.

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 the core resource front-loaded and the scoping caveat immediately after. No filler, no restatement of the name.

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 compensates by describing the return shape (courses with section placements, each tagged with its term). Combined with readOnly annotations and fully documented params, an agent has enough to call this correctly; only result size/pagination is unaddressed.

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

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

Schema description coverage is 100%, with the view enum, district, and studentId all thoroughly documented in the schema itself. The description adds no parameter-level detail, so the baseline of 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 ("Get a student's class roster") and enumerates the payload shape (every course with its section placements). The resource is clearly distinct from siblings like ic_list_grades or ic_list_attendance, though it never names a sibling to sharpen the boundary.

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 clear usage context: the result spans every term of the current enrollment and is deliberately unfiltered, so the caller must narrow it. It stops short of naming an alternative tool or stating when-not-to-use, so it is context rather than routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable behavioral context: it makes one authenticated request, reports round-trip time, and explicitly states it never returns the credential. This goes beyond the annotations without contradicting them.

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 slightly verbose with an awkward phrase ('a your Infinite Campus portal-side problem'), but every sentence contributes information: what it does, what it reports, read-only nature, and when to call. It is front-loaded with the core behavior.

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 adequately describes what is reported: credential source, acceptance, round-trip time, and a hint. It covers the key aspects an agent needs to interpret the tool's output. Some details like error handling are not mentioned, but they are less critical for a healthcheck.

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, and the schema is empty. The baseline for 0 params is 4, and the description correctly focuses on the operation rather than parameters, so no further explanation is needed.

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 the tool's function: it resolves the credential, makes one authenticated request, and reports on credential source, acceptance, round-trip time, and a plain-English hint. It is distinct from sibling tools that list or retrieve specific data (e.g., ic_list_students, ic_get_schedule).

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 instructs when to use: 'Call this when a real tool fails and you want to know which hop broke.' This provides clear context and differentiates from siblings, which are for data retrieval.

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 a safe (readOnlyHint) open-world read, so the bar is lower, and the description still adds real behavior: calendarID is auto-resolved per enrollment and one entry is returned per enrollment, plus a caveat that record shape varies by district and fields pass through unchanged. It does not mention pagination, ordering, or auth requirements, keeping it short of 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?

Three front-loaded sentences: purpose first, then resolution/return behavior, then the shape caveat. Each sentence carries distinct information with no filler, though the third sentence is dense and could be tightened.

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

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

For a read-only list tool, most of the load is carried by annotations and the schema's view documentation; the description fills the remaining need by describing the return granularity (one entry per enrollment) and shape variance, which matters since no output schema exists. Only the undocumented district parameter and absent pagination/ordering detail keep 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?

At 67% schema coverage the baseline sits near 3, and the description adds no parameter-level detail at all. The schema already carries a thorough explanation of the view enum and the studentId source, but the required district parameter is undocumented in both places, a gap the description does not close.

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

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

States a specific verb and resource ("List a student's standardized test scores") and immediately disambiguates the resource as state/national/district tests, which separates it from course-grade siblings like ic_list_grades and ic_list_assignments. An agent can select this tool 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?

Usage is only implied by the data type; there is no explicit when-to-use, no condition for choosing this over ic_list_grades, and no prerequisites or exclusions mentioned. The agent must infer the boundary between "assessments" and sibling list tools on its own.

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 openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: the endpoint returns the entire term history (~hundreds of items) and filtering is client-side, which tells the agent to expect large payloads and that only courseId is filtered server-side.

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, each earning its place: purpose first, then the payload/filtering caveat, then the single-course parameter hint. No filler or restatement of the name.

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, but the description conveys the response's scale and shape (full term history) and the filtering model, which is what an agent needs to call this correctly. Missing only explicit guidance on choosing between this and ic_list_assessments.

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 71% schema coverage, the schema documents most parameters, but the description adds meaning it doesn't: courseId is the sectionID sourced from ic_get_schedule and is the only server-side filter, while since/until/missingOnly are applied client-side. That clarifies the cost and correctness implications of each parameter.

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

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

States a specific verb and resource ("List a student's assignments") and scopes it to a single student. It partially differentiates from the sibling ic_list_assessments by pointing at ic_get_schedule for the courseId source, but it never explains how this differs from the closely-named assessments tool.

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

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

Gives a concrete usage condition for courseId (pass it for a single course) and warns that date/missing filters run client-side against a full-term payload. It stops short of naming alternatives or stating when to prefer ic_list_assessments over this tool, so usage is implied rather than fully routed.

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 openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful behavioral note that enrollmentID is auto-resolved from the student record, but says nothing about pagination, ordering, or what happens when the date range is omitted.

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

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

Two compact sentences with the resource and output shape front-loaded and no filler. Every clause carries information.

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

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

For a 5-parameter read tool with no output schema, the description covers the core identity and the enrollmentID resolution but omits date-range filtering semantics (since/until) and any pagination or volume expectations. Adequate but with clear 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?

The auto-resolution note tells the agent that studentId (not enrollmentID) is the key input, which is real value beyond the schema. However, district and studentId have no schema descriptions and the description does not clarify their formats, so the 60% coverage gap is only partly compensated.

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 (absences and tardies) and clarifies the output shape as a per-course summary grouped by term, which distinguishes it in spirit from the raw-events sibling. It stops short of naming ic_list_attendance_events explicitly, so an agent must infer the summary-vs-event distinction.

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 'List a student's absences and tardies' but there is no explicit when-to-use, when-not, or pointer to the closest alternative (ic_list_attendance_events). The 'Auto-resolves enrollmentID' note hints at a precondition but does not frame it as guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds a genuine behavioral detail beyond the structured fields: enrollmentID is auto-resolved from the student record, so the caller need not supply it. It does not discuss pagination, result volume, or error behavior for a read that can return long event histories.

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 the resource and event types, then return payload, then filters. No filler and no repetition of schema text beyond what is needed for orientation.

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, and the description compensates by naming the fields each event carries (code, description, excuse reason, optional comments). Combined with the filter guidance and the auto-resolution note, an agent has enough to call this correctly for a 6-parameter read tool.

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

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

Schema description coverage is 83%, so the schema already documents since, until, view, studentId, and excusedOnly. The description restates the same since/until and excusedOnly semantics with no added syntax, defaults, or edge-case behavior (e.g., inclusive bounds, interplay with view). Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List individual attendance events') and enumerates the event types (absences, tardies, early releases), which concretely describes what comes back. It does not explicitly name the sibling it differs from, though 'individual events' implicitly separates it from ic_list_attendance.

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

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

Gives concrete usage for two parameters ('use since/until to filter by date and excusedOnly to show only excused events'), which implies the narrowing workflow. However, it never states when to prefer this tool over ic_list_attendance or other attendance-related siblings, and there are no exclusions or prerequisites beyond the implicit studentId.

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 safety (readOnlyHint) and scope (openWorldHint), so the description adds real value by disclosing a non-obvious failure mode: a FeatureDisabled result detected via displayOptions or a 404 backstop. It omits pagination, rate limits, or result-volume behavior, 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 sentences, purpose front-loaded and the error caveat second. Every clause carries information; nothing is padding.

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

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

For a read-only list tool with no output schema and readOnly/openWorld annotations, the description covers purpose and the key failure mode. It is thin on date-filter semantics and result shape, but those are partly served by the view parameter's schema description.

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 60% and the description explains none of the parameters: view, since, and until are documented only in the schema, and district/studentId have no schema descriptions at all. The single mention of "district" is contextual (module toggle), not a semantic explanation of the required parameter.

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

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

The first sentence gives a specific verb and resource ("List a student's behavior events / referrals"), which cleanly separates it from sibling listers like ic_list_attendance or ic_list_fees. It does not explicitly name a sibling or contrast scope, so it stops short of a 5.

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

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

The description gives useful context about when the tool fails (module disabled at the district) but never states when to reach for this tool versus the other 18 ic_list_* siblings, nor when the since/until filters should be applied. Usage is only implied by the tool 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 establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful detail that the response contains names and base URLs and explicitly excludes credentials, but does not describe authentication, rate limits, or other behavioral constraints.

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 resource, and the return-content clarification earns its place. There is 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 simple one-parameter listing tool with no output schema and rich annotations, the description covers what is returned and what is excluded (credentials). It does not mention ordering, pagination, or when to call it, but those are secondary given the tool's simplicity.

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 optional view parameter is documented in the schema in detail. The description adds no parameter-level meaning, which is acceptable at this coverage level.

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 (List) and resource (Infinite Campus districts configured for this MCP server), and it clearly distinguishes itself from sibling tools like ic_list_teachers or ic_list_students through the unique resource it targets.

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 says what the tool returns, but provides no when-to-use guidance, no prerequisites, and no alternatives or exclusions. The agent must infer that this is a discovery/config-listing tool from context 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 cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description still adds value by declaring that only metadata is returned and by disclosing the FeatureDisabled error state, which is not derivable from 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?

Three short sentences, front-loaded with the primary action, followed by the routing pointer and the error condition. No filler or restatement of the tool name.

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 return-value burden and does state 'metadata only' plus document examples, and it covers the error case. It could say slightly more about which metadata fields appear, but it is adequate for a simple list endpoint.

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 33%: only 'view' is documented in the schema, and it is documented thoroughly (compact vs full, no field projection). The description adds nothing about 'district' or 'studentId' beyond their self-evident role as required identifiers, and does not compensate for the undocumented parameters. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List a student's available documents') and enumerates concrete examples (report cards, transcripts, schedules). It is immediately distinguishable from the sibling ic_download_document, which it explicitly names as the file-fetching counterpart.

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: metadata listing here, file retrieval via ic_download_document. It also names the failure condition (FeatureDisabled when the district module is off), so the agent knows when this call will not yield 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 only declare readOnlyHint and openWorldHint; the description adds substantial non-obvious behavior: the tool fans out to two endpoints, degrades to 'PartialSuccess' with an issues[] array when one side fails, and returns FeatureDisabled only when both 404. That is exactly the kind of partial-failure contract an agent needs.

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 first, then the endpoint-combination detail, then the failure contract. Every sentence carries information, though the failure-mode sentences could be compressed slightly.

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 aggregating list tool with no output schema, the description covers purpose and the tricky partial-failure behavior well. It stops short of describing what the returned fee/balance records contain, which an agent would otherwise have to discover empirically.

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 67% and the description contributes nothing about view, district, or studentId; the schema itself documents view (with its compact/full tradeoff) and studentId's provenance. The undocumented district parameter is left unexplained in both places, so this sits at the baseline rather than above it.

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 — listing a student's fee assignments and running balance/surplus — and clarifies that it aggregates two underlying endpoints. No sibling tool covers fees, so the agent can route here unambiguously from the sibling list.

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

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

Usage is implied by the resource (get fees for a given student), but there is no explicit when-to-use/when-not framing or named alternative. The failure-mode note (FeatureDisabled only when both endpoints 404) is behavioral rather than selection guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds genuine value beyond that by disclosing the FeatureDisabled error and how it is detected (displayOptions / 404 backstop). It stops short of other behavior an agent would want, such as auth requirements, rate limits, or how far back 'recent' reaches.

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 tightly written sentences with the core capability front-loaded and the notable failure mode second. No filler, no repetition of the title or annotations.

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

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

For a read-only tool with no output schema, the safety and error behavior are adequately covered, but the description leaves open how many transactions are returned, whether results are paginated, and what 'recent' means by default. It also gives no clue about what the balance/transaction payload contains. Adequate but with clear 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?

The description says nothing about any of the five parameters. Schema coverage is only 60%: view, since, and until are well documented in the schema, but district and studentId have no description anywhere. With a mid-range coverage gap and zero compensating detail in the description, this falls below the 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 (List) and a specific resource (student's lunch balance and recent food-service transactions), which an agent can distinguish from sibling list tools like ic_list_fees or ic_list_assignments. It does not, however, explicitly contrast itself with the nearby money-domain sibling ic_list_fees, 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?

There is no when-to-use guidance, no stated prerequisites (e.g., permissions, which studentId format is accepted), and no naming of alternatives such as ic_list_fees for non-food-service charges. The only usage-adjacent information is the FeatureDisabled failure mode, which is a behavioral note rather than routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds scope ('term grades and in-progress'), but says nothing about behavior when termId is omitted, pagination, or result size. With annotations carrying the safety burden, a 3 is warranted.

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 the resource front-loaded and no filler. It is appropriately sized, though the brevity is partly the cause of the gaps elsewhere.

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 tool with no output schema and 75% of parameters undocumented, the description is too thin. It omits termId/default behavior, pagination, and any routing against ic_list_recent_grades, leaving the agent under-equipped to call it correctly.

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

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

Schema coverage is only 25% – only the 'view' enum has a description, while termId, district, and studentId are bare. The description does not compensate: it never explains what termId does, whether it defaults to the current term, or the format of the identifiers. It merely echoes the words 'term' and 'student'.

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 ('a student's term grades and in-progress course grades'), and the phrase 'term... and in-progress' hints at the distinction from the ic_list_recent_grades sibling. It does not explicitly name that sibling, so the differentiation is implied 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?

There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternative ic_list_recent_grades. An agent must guess whether this or the 'recent grades' tool is appropriate.

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 readOnlyHint and openWorldHint, and the description goes well beyond them: per-section degradation on error, the fact that `limit` governs only the high-volume prism source, the read-tracking caveat, and an explicit untrusted-content warning. These are behavioral traits an agent cannot get 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?

Dense but front-loaded: the source enumeration comes first, followed by error behavior, the limit scoping, the read caveat, and the safety warning. Every clause carries information, though the limit/read sentences could be tightened without loss.

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 takes on the burden of describing the return shape ('each section has its own count and items', error field isolation) and does so. For a three-source aggregator with open-world annotations, 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 coverage is 67%, so `limit` and `view` are already documented in the schema, and the description's limit statement largely duplicates it. `district` has no description in either place, and the description adds no new semantics for the enum. This lands at the baseline for partially-covered parameters.

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

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

States a specific verb and resource ('List all parent-visible messages') and enumerates the exact three sources it aggregates (prism notifications, Messenger 2.0 inbox, portal userNotice). It distinguishes itself from the sibling ic_get_message by pointing at it for full HTML bodies, so an agent can route without opening schemas.

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 clear routing guidance: use ic_get_message for the full HTML body, and use this tool for the combined listing. The note on read-tracking behavior adds useful context. It does not explicitly enumerate when *not* to use it (e.g., for attachments or documents, which other siblings cover), so it stops short of full alternative 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=true and openWorldHint=true, so safety is covered. The description usefully adds that filtering happens server-side via scoreModifiedDate and defaults to a 14-day window, but says nothing about pagination, result caps, or how a missing student/district is handled.

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 purpose, then scope, then the parameter control. Slight redundancy between the description's since guidance and the schema's identical note, 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 4-parameter read tool with no output schema and only safety annotations, the description covers the recency scope and cutoff default adequately, but leaves the district parameter's meaning and the response shape (delegated to the enum in schema) unaddressed.

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

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

Schema description coverage is 50%: `view` and `since` are documented in the schema, while `district` and `studentId` have no description anywhere. The description echoes the since semantics already stated in the schema and only hints at studentId ("for a student"), leaving district entirely unexplained, so it does not fully compensate for the gap.

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

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

States a specific verb and resource ("List recently-graded assignments") and scopes it to a single student, which implicitly separates it from the broader ic_list_grades and ic_list_assignments. However, it never names those siblings or states the difference explicitly, so the agent must infer the distinction.

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 word "recently-graded" and the 14-day default imply the use case, and the since parameter gives a control for widening it. But there is no explicit when-to-use/when-not guidance and no routing to alternatives like ic_list_grades for the full history.

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 carry readOnlyHint/openWorldHint, so the description does the heavy behavioral lifting: it discloses the grouped-by-term response shape, that days carry comments when labelled, that labelled daysOff (including between-term breaks) are attached, and the exact 'SchoolDaysUnavailable' warning path with campusVersion. This is rich edge-case disclosure beyond what annotations provide.

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

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

The response-shape detail is front-loaded and each sentence carries distinct information (structure, comments, daysOff, range filter, warning case). It is dense and long, but nothing is redundant; a slight trim of the parenthetical examples would tighten it.

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

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

With no output schema and an openWorld read tool, the description fully compensates by describing the returned entries, term boundaries, daysOff, labels, and the unavailability warning. An agent has everything needed to interpret the result 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 80% (view enum and since/until formats documented in the schema), so a 3 is the baseline. The description adds meaning by explaining that since/until bound the day range, and studentId's schema already points at ic_list_students. It does not add anything for view/district 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?

States a specific verb+resource ('List a student's school days (instructional calendar)') and distinguishes itself from siblings like ic_list_attendance by scoping to the instructional calendar grouped by term. An agent can identify exactly what this returns 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?

Gives clear context ('Use since/until to narrow the range') and implies the read-only listing use case, but never names an alternative sibling (e.g. ic_list_attendance) or states when NOT to use this tool. Clear usage without explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description adds the account/district scoping constraint but says nothing about pagination, result size, or rate limits, which matters for a live external district API.

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 brevity comes partly from omitting guidance rather than from tight editing.

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 no output schema, the description states what it returns at a high level and nothing is strictly wrong or missing. However, it omits any hint of result shape or volume, which is the main thing an agent would otherwise wonder about.

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 the district lookup and the compact/full view semantics are fully documented in the schema. The description adds no parameter detail beyond restating the district condition, 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?

Specific verb ("List") plus resource ("students") and a clear scope ("enrolled under the parent account for a given district"). This naturally separates it from ic_list_teachers and ic_list_districts, though it never names a 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?

There is no when-to-use guidance, no mention of prerequisites (e.g. needing a district value from ic_list_districts), and no exclusions or alternatives among the many ic_list_* siblings. Usage must be fully inferred from the one-line purpose.

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 and openWorldHint, yet the description adds genuinely useful behavioral context: it merges two upstream endpoints (section/contacts and studentCounselor/byUser), and it warns that response field shapes vary by district while core fields are stable. That variability warning is not derivable from the annotations or schema.

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

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

Two sentences, both earning their place: the first front-loads purpose, the second carries the merged-endpoint and field-variability caveat. No filler or restatement of the tool name.

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

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

With no output schema, the description usefully pre-announces response shape variability and core fields. Combined with read-only annotations this is close to complete; only the district and studentId parameters are left unexplained.

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 only 33%, and the description adds no meaning for district or studentId beyond implying 'a student's' identity. The one documented parameter (view) is thoroughly explained in the schema itself, so the description neither helps nor compensates for the two undocumented required parameters.

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

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

States a specific verb and resource ('List a student's teachers... and assigned counselor(s)') and scopes it to enrolled sections. No sibling tool (ic_list_students, ic_get_schedule, etc.) covers teachers/counselors, so an agent can distinguish it on the resource alone without opening a 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?

Usage is only implied: the required district/studentId make clear it is a per-student lookup, but there is no explicit when-to-use or when-not-to-use guidance versus siblings such as ic_list_students or ic_get_schedule. Nothing misleading, but nothing that routes the agent either.

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