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

Annotations already flag destructiveHint=true and openWorldHint=true, so the base safety profile is known. The description goes further: it discloses the side effect on transportation eligibility, the mandatory confirmation path, that the first call returns a preview payload rather than mutating, and that only a repeat call with the token commits. This is exactly the extra context a write tool 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?

Front-loads what the tool does, then immediately the confirmation consequence. Dense but every clause carries information; the only minor redundancy is restating the required fields already marked in 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 cover the interaction pattern, and it does: preview payload shape, token round-trip, and the elicitation alternative. It stops short of describing validation failures (e.g. negative radius) or success response shape, a small gap for a destructive write 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 100%, so the baseline is 3. The description still adds value by naming the verified required fields (studentId, radius) and by framing confirmToken's role in the call sequencing, reinforcing the token description's 'never on the first call, never reused' rule rather than merely repeating types.

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: 'Set a student's walk-zone radius, in meters.' That is unambiguous and clearly distinct from the read-oriented siblings (get_student, list_students, get_settings). An agent can identify the operation 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?

Explains the confirmation gating precisely — elicitation prompt when supported, otherwise a two-phase preview + confirmToken flow — and names MCP_CONFIRM_MODE as the governing setting. It does not, however, say when this tool is preferable to alternatives or what prerequisites (permissions, student state) are 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the response includes the current server date, which hints the call returns live state, but it says nothing about auth requirements or whether data is cached.

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 names the resource first and then the payload. Every clause earns its place with 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 zero-parameter read with no output schema, the description usefully enumerates the key return fields (name, timezone, formats, server date), which compensates for the missing output schema. It could still note when this is preferable to get_profile/get_settings.

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 correctly implies no input is required, and there are no parameter semantics to document.

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

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

States a specific verb (Get) and resource (the account / school district), and enumerates the returned fields: name, timezone, date/phone formats, plus the current server date. This clearly differentiates it from list_* siblings, though the boundary with get_profile and get_settings is not explicitly drawn.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of the alternatives (get_profile, get_settings) that return overlapping context. Usage is only implied by the tool name and returned fields.

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=true, openWorldHint=true), and the description adds genuinely useful behavior beyond them: this returns the last known position, and the result is empty when the bus is not running. That edge-case disclosure prevents an agent from misreading an empty payload as an error, though freshness/staleness timing and auth requirements are unstated.

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

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

Two sentences with zero waste. The core action is front-loaded, and the field list plus the empty-result caveat are tightly packed into the remainder.

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 it well by naming latitude, longitude, speed, and vehicle id, plus the empty-result case. It stops short of describing error conditions or how stale the 'last known position' may be.

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 schema already documents both studentId (with its source tool) and the AM/PM enum semantics. The description's reference to the 'selected run (AM or PM)' merely echoes the schema, adding no syntax or format detail. 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 (Get) and resource (live GPS location of a student's bus) scoped to the selected AM/PM run. No sibling tool covers bus location, so an agent can immediately route here rather than to get_student or get_student_stops.

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 implies usage context via 'for the selected run (AM or PM)' and 'empty when the bus is not currently running', which tells the agent the expected precondition. However, it names no alternative tool and gives no explicit when-not-to-use guidance, leaving usage 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 openWorldHint=true, so the safety profile is covered. The description adds the returned field set, but says nothing about authentication requirements, behavior when the session is unauthenticated, or data freshness — modest added value on top of 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?

A single, front-loaded sentence with the verb and subject first and the payload detail in parentheses. There is no filler and nothing that fails to earn 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?

With no output schema, the description partially compensates by naming the returned fields, which is the main thing an agent needs. It is nearly complete for a trivial zero-param read, with only edge behavior (unauthenticated session, error shape) left 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly implies the target is implicit (the signed-in user) rather than passed in.

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 the signed-in user profile") and even enumerates the returned fields (name, email, role, account), so the agent knows exactly what it gets. It does not, however, distinguish itself from the close sibling alphaportal_get_account, leaving a plausible ambiguity unresolved.

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 "signed-in user" implicitly scopes usage to the current session and hints it is not the tool for arbitrary accounts, which is useful context. But there is no explicit when-to-use/when-not statement and no named alternative to compare against, so an agent must 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 only declare readOnlyHint and openWorldHint, so the description carries the important behavioral load and does so well: single-use URL, credential-like, usable by anyone holding it without signing in, and explicit handling warnings. This is exactly the security context an agent needs before surfacing the link.

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 zero padding: the first describes the operation and return, the second front-loads the security constraint before any elaboration. 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?

There is no output schema, yet the description still tells the agent what comes back (a browser-openable URL) and how that URL behaves. Combined with the single-parameter schema and annotations, nothing needed to invoke or relay the result 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?

Only one parameter, and schema description coverage is 100% — the schema already documents studentId as the numeric ID from alphaportal_list_students. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (get) and resource (one-time PDF download link) plus the report contents (stops, schedule). An agent can tell this apart from read-only siblings like alphaportal_get_student_stops, which return data directly rather than a download URL.

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 handling guidance ('hand it only to the signed-in user') but never says when to choose this tool over alphaportal_get_student_stops or alphaportal_get_student, which cover similar data. Usage is implied by the return type, not stated as a selection rule.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful scoping context (settings are per-district, covering notification types and enabled features), but does not mention return shape, caching, or 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?

A single front-loaded sentence with no filler; the clarifying parenthetical earns its place by telling the agent what the opaque word 'settings' actually contains.

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 no output schema, the description adequately conveys both the source and nature of the data. It stops short of describing the return structure, but the parenthetical gives enough for correct invocation and interpretation.

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 per the rubric the baseline is 4; there is nothing for the description to disambiguate. The description correctly implies the call is parameterless by scoping to 'this district' implicitly through context rather than an argument.

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

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

States a specific verb (Get) and resource (portal feature/visibility settings), and the parenthetical clarifies exactly what those settings contain (notification types and features for the district). An agent can distinguish it from write-side siblings like alphaportal_set_notification and from unrelated reads like alphaportal_get_profile, though no sibling is named.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as alphaportal_get_profile or alphaportal_get_account. The agent must infer from the noun alone that this is the tool for reading district-level portal configuration.

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 the scope of returned data (school, stops, times, calendars), which is useful, but discloses nothing about permissions, failures for unknown studentIds, or whether the call reaches a live district system despite openWorldHint.

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, and the returned content is listed immediately after the verb. Nothing could be removed without losing 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 simple one-parameter read tool with annotations covering safety, this is nearly complete. Because no output schema exists, the description carries the return-shape burden and does outline the main fields, though it stays at a summary level.

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?

Only one parameter exists and schema coverage is 100%; the schema already documents studentId and even points to alphaportal_list_students as its source. The description adds nothing about the 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 and resource ('Get a student's full transportation detail') and enumerates what is returned — assigned school, morning/afternoon stops, times, calendars. It does not distinguish itself from the sibling alphaportal_get_student_stops, whose name suggests the same stop data, so an agent cannot cleanly tell the two apart from the description 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives. The overlap with alphaportal_get_student_stops is left unresolved, leaving the agent to guess which tool to call for stop information.

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 real value beyond that by disclosing the shape of the response (stop name, scheduled time, days of the week, lat/lng), which matters because no output schema exists. It still omits any mention of empty results or error behavior for an unknown studentId.

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; the resource comes first and the return fields follow as a compact list. 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 single-parameter, read-only lookup with no output schema, the description supplies enough to call it correctly and to know roughly what comes back. Minor gaps remain around empty/error results and how the stops relate to the live-location sibling, but 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?

Only one parameter, and the schema already documents it at 100% coverage, including its origin (alphaportal_list_students). The description adds nothing about the parameter itself, 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?

The description names a specific verb and resource ('Get a student's assigned bus stops') and enumerates the returned fields (stop name, scheduled time, days, lat/lng), which is far more than a restatement of the tool name. It does not, however, explicitly distinguish itself from the similarly-named sibling alphaportal_get_bus_location, so an agent must infer the split between 'assigned stops' and 'live bus position'.

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 or when-not-to-use guidance and no alternatives are named. The only routing hint available to the agent lives in the schema ('from alphaportal_list_students'), not in the description, which leaves the boundary with alphaportal_get_bus_location unstated.

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 (readOnly, idempotent, openWorld), and the description adds substantive behavior beyond them: it makes a live outbound request, it never returns the credential itself, it reports the credential's source, round-trip time, and a hint that separates 'no credential' from 'rejected' from 'server-side problem'. That error taxonomy is exactly the context an agent needs to interpret the result.

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

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

Three sentences, front-loaded with what it does before when to call it. Every clause carries information — credential source, acceptance, timing, error hint, non-disclosure — with no restatement of the title or 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?

No output schema exists, so the description carries the burden of describing the response, and it does so well by enumerating source, acceptance, latency, and the error-distinguishing hint. Nothing needed to call or interpret this diagnostic tool 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 schema takes no parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly signals a zero-argument invocation by describing the whole operation as parameterless.

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 concrete two-step action (resolve the credential, make one authenticated request to api.alpharoute.app) and a concrete output shape. This is unmistakably distinct from every sibling tool, which fetch portal data or mutate settings.

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?

"Call this when a real tool fails and you want to know which hop broke" is an explicit trigger condition tied to the failure mode of sibling tools. There is no stated when-not and no alternative diagnostic named, but the framing already scopes it to diagnostics rather than routine data access.

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 only the return shape (id + name), which is mild extra value; it says nothing about ordering, completeness of the district-wide list, or freshness of the data.

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 short sentence carrying the verb, the resource, its scope (district-level), and the payload fields. Nothing is padded and the key information 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-only list with no output schema, the description supplies enough: what is listed, at what scope, and the fields returned. A note on ordering or whether the list is exhaustive would close the remaining 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?

The tool takes zero parameters, so there is no parameter semantics to document – the baseline for a parameterless tool is 4. The description does not need to compensate for any schema gap 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?

States a specific verb and resource ('List the district grade levels') and even names the returned fields (id + name), so the agent knows exactly what it gets back. It does not, however, differentiate itself from siblings like alphaportal_list_schools or alphaportal_list_students beyond the resource noun.

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: this is reference-data lookup for grade levels. There is no explicit when-to-use, no statement of prerequisites, and no routing to or away from any sibling, so an agent must infer the context.

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, covering the safety profile. The description adds important behavioral context: the returned text is third-party authored and must be treated as data, never instructions, which is a valuable trust/safety disclosure not present in 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?

The definition is compact and front-loaded: it first states what is listed and what fields are returned, then follows with the critical untrusted-content warning. No sentence is wasted.

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

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

For a zero-parameter, read-only list tool with no output schema, the description sufficiently explains the returned content (title, body, student, timestamp) and adds an essential security caveat. An agent has everything needed to call and correctly interpret the tool.

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

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

Parameter count is 0, so the baseline score is 4. The description does not need to compensate for missing parameter documentation, and it correctly avoids discussing parameters that do not 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?

The description states a specific verb (List), resource (account's transportation notifications), and content scope (arrival/departure alerts with title, body, student, timestamp). It clearly distinguishes this read operation from the sibling set_notification 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?

No explicit when-to-use, when-not-to-use, or alternative-tool guidance is provided. The purpose implies a list operation, but the description does not help an agent choose between this and other read tools like get_bus_location or set_notification.

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 only that results carry tracking numbers and status; it says nothing about result volume, pagination, ordering, or the openWorld implications of tracking data.

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

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

One front-loaded sentence with no filler; the resource and the key return fields are both stated up front and every word 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?

With no parameters, no output schema, and annotations covering only safety, the description partially compensates by naming the return fields (tracking numbers, status). It still leaves unanswered how many requests come back, whether results are paginated or ordered, which an agent listing an account's requests would want to know.

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. There is nothing for the description to disambiguate, and the schema is complete by definition.

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 ('List') and a specific resource ('transportation requests submitted on this account'), plus the salient return fields. It does not, however, distinguish itself from the other list_* siblings (schools, grades, students, notifications) beyond naming its own resource, so an agent gets no explicit routing cue.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as get_student_stops or list_notifications. The agent must infer from the name alone that this is the account-wide request listing.

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 that the tool returns names and coordinates and that it enumerates ALL schools (no pagination parameters), which is useful context, but it says nothing about ordering, failure modes, or result size.

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 waste, front-loaded with the core action and resource followed by a purpose note. Nothing could be trimmed without losing 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 trivial read-only list tool with no parameters and no output schema, the description adequately covers what is returned (names and coordinates). No return-format detail is required given the absence of an output schema, though slightly more on result shape would help.

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 beyond what the (empty) schema shows. Baseline 4 applies for a no-parameter tool.

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 schools in the district') plus the payload returned (names and coordinates). The resource noun 'schools' naturally distinguishes it from sibling list tools like list_students and list_grades, though it does not name an alternative explicitly.

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

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

'Useful for resolving a school by name' provides an implied use case, giving the agent some sense of when to reach for it. However, there are no exclusions, prerequisites, or reference to sibling tools, so the guidance remains at the implied level.

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?

With readOnlyHint=true and openWorldHint=true already declaring the safety and scope profile, the description adds value by enumerating the fields returned (grade, school, transportation flags) — useful since no output schema exists. It also implies the session/auth requirement via 'signed-in account'. It says nothing about empty results or data freshness.

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, and the scope statement plus the routing cue are front-loaded. Every phrase 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, read-only list call with no output schema, the description covers scope, returned content, and usage entry point — enough to invoke it confidently. Minor gaps (empty-list behavior, whether the account could have zero students) are negligible.

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 per the baseline there are no argument semantics to explain. There is no risk of the description misleading about 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?

States a specific verb and resource (list the students/children on the signed-in account) and even previews the payload ('grade, school, and transportation flags'). It is clearly distinguished from the singular alphaportal_get_student, though that sibling is never 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?

'Start here to get each studentId' gives a clear entry-point cue that this is the prerequisite call for ID-consuming siblings like get_student and get_student_stops. It does not name those alternatives or state any exclusions, so it stops short of full when/when-not 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 the safety profile is covered; the description still adds real value by disclosing the token-resolution order (env var, saved session, bridge browser tab) and the important guarantee that no credentials are returned. It stops short of describing the failure/return 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 tightly written sentence with the purpose front-loaded and the credential-safety guarantee appended. Every clause carries 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?

With no parameters and no output schema, the description covers the essential context: what it checks, how it obtains tokens, and that it returns no credentials. The only gap is what a successful or failed check actually returns to the caller.

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 correctly implies no input is needed and instead explains the implicit inputs (environment variable, saved session, browser bridge) that drive behavior.

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

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

States a specific verb and resource ('Check whether the server can authenticate to AlphaPortal') and details the internal mechanism (refresh-token resolution then access-token minting). It is clear on its own, but does not distinguish itself from the close sibling alphaportal_healthcheck, leaving some ambiguity about which diagnostic to pick.

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 description makes clear it is a pre-flight authentication check, and it enumerates the token sources it falls back to. There is no explicit 'use this when X, use healthcheck when Y' guidance or any stated exclusion.

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 destructiveHint=true and idempotentHint=true, but the description adds behavior the annotations cannot: the whole preference set is submitted at once, omitted categories may be left unchanged or reset by the server, a preview payload plus confirmToken gates the real mutation, and the token must never be invented or reused. That is exactly the side-effect detail an agent needs before mutating 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 action is front-loaded in the first sentence, followed by the confirmation mechanics and a capitalized NOTE for the dangerous partial-set behavior. It is dense with parentheticals and inline caps (MCP_CONFIRM_MODE) but every sentence carries distinct operational information, so nothing is wasted.

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

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

For a destructive, nested-object mutation with no output schema, the description covers the confirmation gate, the preview/confirmToken flow, and the risk of omitted categories. It stops short of describing permissions/auth requirements, error responses, or whether partial writes are atomic, which would matter for a destructiveHint=true 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 100%, so the baseline is 3, and the description earns an extra point by naming the five category keys the district may enable and framing each as AM/PM push/email toggles. The confirmToken semantics are reinforced but largely restate the schema's own description, so it is not fully additive.

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 clause gives a specific verb (Set), resource (student's transportation notification preferences), and scope (push/email, per AM/PM run), then enumerates the exact category keys. This distinguishes it cleanly from the sibling read tool alphaportal_list_notifications without needing to open 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?

It clearly states the preconditions for calling: user confirmation first, either via client elicitation or via a two-step preview/confirmToken round trip, and points to MCP_CONFIRM_MODE. It does not explicitly contrast when to use this vs. alphaportal_list_notifications or note prerequisites like district-enabled categories, so it falls short of full when/when-not routing.

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