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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation/safety profile is covered. The description adds valuable behavioral context: it can affect transportation eligibility, it triggers a confirmation prompt where supported, and otherwise the first call returns a preview plus confirmToken, and only a repeat call with that token proceeds. This goes beyond the annotations. Minor gap: it doesn't state whether the operation is reversible or what happens after confirmation, but the core behavior is well disclosed.

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 compact and well-structured: a single opening sentence stating the purpose, followed by a focused explanation of the confirmation flow and a 'Verified required fields' line. Every sentence earns its place, and the most important behavioral detail (confirmation requirement) 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?

Given the tool's complexity (confirmation modes, token flow) and that there is no output schema, the description explains the two-step fallback thoroughly enough for an agent to understand the flow. It could add what the confirmation-required response looks like or what the final response returns, but the essential call pattern is clear: first call previews, second call with confirmToken proceeds. It is complete enough for correct invocation.

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 schema fully documents all three parameters and their constraints, including the special usage rules for confirmToken. The description adds the clarification that verified required fields are studentId and radius, and that the API stores the base-unit distance (echoing the schema's radiusMeters description). It does not add new syntax or format details beyond the schema, so the 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?

The description states a specific verb ('Set'), a specific resource ('a student's walk-zone radius'), and the unit ('in meters'). It clearly differentiates this from sibling tools, which are mostly read-only getters/listers; the only other 'set' sibling, alphaportal_set_notification, has a different resource. The description also mentions a key effect (transportation eligibility), adding clarity beyond the tool name.

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

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

The description explains when to use it (to set a student's walk-zone radius) and explicitly describes the confirmation workflow: a prompt for clients that support elicitation, or a two-step token flow otherwise. It warns about the effect on transportation eligibility, implying caution. It does not explicitly name an alternative tool, but the context signals show only one other 'set' tool with a different resource, so the usage guidance is sufficient.

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 indicate readOnlyHint=true, and the description's 'Get' is consistent. The description adds context about the returned content (including server date), but does not disclose additional behavioral traits such as authentication requirements or rate limits. It provides modest value beyond the annotation.

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

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

The description is a single, clear sentence with no filler. It front-loads the action and lists the key returned data efficiently.

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

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

For a simple read-only tool with no parameters and no output schema, the description adequately covers what is returned. It mentions all relevant data points, making it complete for an agent to know what to expect.

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 no parameters, and the schema coverage is 100% (empty). The description does not need to explain parameters, so it meets the baseline for zero-parameter tools.

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 retrieves account (school district) information, listing specific attributes (name, timezone, date/phone formats) and the current server date. It distinguishes itself from siblings by focusing on account-level info, not settings or profile.

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 does not provide any guidance on when to use this tool versus alternatives like alphaportal_get_settings or alphaportal_get_profile. It simply states what it does without exclusions or recommendations.

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 description discloses that it returns the last known position and that it is empty when the bus is not currently running. This adds behavioral context beyond the readOnlyHint annotation. It doesn't mention rate limits or data freshness, but the key behavior (last known position, empty when not running) is clearly stated.

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

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

The description is two sentences, front-loaded with the main purpose and return values, and includes the edge case (empty when not running) without any fluff. Every sentence earns its place.

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

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

For a read-only tool with 2 fully documented parameters and no output schema, the description covers the essential behavior: what it returns, when it's empty, and the AM/PM distinction. It could mention whether the location is a single point or a history, but the phrase 'last known position' clarifies that. The lack of an output schema means the description's list of fields (latitude, longitude, speed, vehicle id) is valuable and sufficient.

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 schema already documents both parameters. The description adds the context that studentId comes from alphaportal_list_students, which is helpful, but it doesn't add much beyond the schema. 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?

The description clearly states the tool's purpose: getting live GPS location of a student's bus for a selected run. It specifies the exact data returned (latitude, longitude, speed, vehicle id) and distinguishes it from other alphaportal tools by focusing on bus location rather than student info, notifications, or 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?

The description implies when to use this tool: when you need a bus's live location for a student's AM or PM run. It doesn't explicitly name alternatives or exclusions, but the context of sibling tools (e.g., alphaportal_get_student, alphaportal_get_student_stops) makes the use case clear. It also notes the empty result when the bus is not running, which helps the agent decide if the 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=true, and the description adds the concrete return fields and user scope, which is useful beyond the annotation alone. It does not describe error behavior or authentication failure handling, but for a simple read-only getter, the combination of annotation and description is adequate.

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 conveys verb, resource, and return fields with zero extraneous words.

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 profile retrieval tool, the description is complete: it states what is returned and who it applies to. No output schema exists, so the explicit field list is especially valuable, and the annotations cover the safety profile.

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 additional to document. The baseline of 4 applies, and the description correctly avoids fabricating parameter details.

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?

Description states a specific verb ('Get') and resource ('signed-in user profile'), and enumerates the returned fields (name, email, role, account). This distinguishes it from sibling tools such as get_account and session_status, which target different resources/concerns.

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

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

The description makes the intended use clear: retrieve the profile of the currently authenticated user. It does not explicitly exclude alternatives or state when to choose this over sibling tools, but the specificity of 'signed-in user profile' provides sufficient context for an agent to select it appropriately.

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 annotation readOnlyHint=true already covers safety, and the description adds crucial behavioral detail: the link is 'one-time' (single-use) and must be 'opened in a browser'. This goes beyond the annotation and informs the agent of link expiry and usage constraints, which is valuable for a correct invocation.

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

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

The description is a single, front-loaded sentence that states the purpose and return type without extraneous detail. Every word adds value, making it highly efficient for an agent to parse.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers the essential points: what it returns (a one-time URL), what it contains (report with stops and schedule), and the intended usage (open in browser). No critical information is missing for correct invocation.

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 covers the single parameter studentId with a description that references alphaportal_list_students, providing full context. The tool description adds no parameter-specific information, so it relies entirely on the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Get'), the specific resource ('one-time PDF download link for a student's transportation report'), and the content of the report ('stops, schedule'). It also distinguishes itself from sibling tools that return data directly (e.g., alphaportal_get_student_stops) by emphasizing the link, not the data itself.

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 provides clear context—it is for obtaining a PDF link of a transportation report—but does not explicitly name alternatives or when not to use it. The agent can infer it is for report downloads rather than live data, but no direct comparison to siblings is given.

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

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

Annotations already declare readOnlyHint=true, and the description uses 'Get', which is consistent. The description adds value beyond the annotation by specifying the scope (district-level) and the exact content returned (notification types and features). This contextual detail is not present in the annotation, so the description enhances transparency.

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

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

The description is a single, well-structured sentence. It front-loads the primary action ('Get the portal feature/visibility settings') and immediately clarifies the content scope in parentheses. No filler words; every part contributes to understanding.

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 tool with no parameters and no output schema, the description is largely complete: it states the action, the resource, and the returned content. The only minor gap is not specifying the return format (e.g., object vs. list), but given the low complexity and read-only annotation, this is not critical. A score of 4 reflects that it could be slightly more explicit but is otherwise adequate.

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

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

There are zero parameters, and the schema coverage is 100% (vacuous). The description does not need to add parameter details. Baseline for 0 params is 4, and the description appropriately omits any parameter-related information, so a score of 4 is warranted.

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

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

The description uses a specific verb ('Get') and resource ('portal feature/visibility settings'), and explicitly states what it returns: which notification types and features are enabled for the district. This clearly distinguishes it from sibling tools like list_students or get_profile, and leaves no ambiguity about the tool's role.

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 when to use the tool: when you need to know which portal features/notifications are enabled for the district. It does not explicitly mention alternatives or exclusions, but the context 'for this district' adds a scoping clue. No direct sibling for settings exists, so the guidance is adequate though not exhaustive.

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 description is consistent with the readOnlyHint annotation and adds useful return-behavior context by listing what the response contains: assigned school, stops, times, and calendars. It does not go deeper into auth requirements, failure modes, or response formatting, but the annotation already establishes the safety profile.

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

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

The description is a single front-loaded sentence that states the action and resource first, then uses a colon to efficiently list the included details. There is no filler or redundant material.

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 single-parameter read-only tool, the description covers the main return categories, and the schema fully documents the required input. The only notable gap is the lack of explicit differentiation from alphaportal_get_student_stops, but the tool is still callable without missing critical information.

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

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

Schema coverage is 100%: the single studentId parameter is fully described in the schema, including its source from alphaportal_list_students. The description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description names a specific verb and resource: 'Get a student's full transportation detail,' and it enumerates the included content (assigned school, morning/afternoon stops, times, calendars). However, it does not explicitly differentiate this tool from the overlapping sibling alphaportal_get_student_stops, 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?

There is no guidance on when to use this tool versus alternatives. The overlap with alphaportal_get_student_stops is especially relevant, yet the description never says 'use this for full transportation detail' or 'use get_student_stops for stops only.' The usage context is left entirely to inference.

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

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

The readOnlyHint=true annotation already establishes that this is a safe read operation. The description adds value by listing the output fields, which is useful behavioral context, but it does not disclose any additional behavior such as response format, ordering, or possible empty results. This is acceptable for a simple read-only lookup.

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

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

The description is a single, front-loaded sentence that immediately states the tool's purpose and then compactly lists the return contents. There is no filler or redundant 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 one-parameter, read-only tool with no output schema, the description adequately states what data will be returned. It is slightly incomplete only because it does not indicate when to prefer this tool over related sibling tools, but the low complexity and strong schema coverage make it otherwise sufficient.

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

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

Schema description coverage is 100%: the only parameter, studentId, is fully documented in the schema as an integer sourced from alphaportal_list_students. The description itself adds no additional parameter semantics, 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 ('Get'), a specific resource ('a student's assigned bus stops'), and explicitly lists the returned fields (stop name, scheduled time, days, lat/lng). This clearly distinguishes it from siblings like alphaportal_get_bus_location, which would cover live bus location rather than assigned 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?

There is no guidance about when to use this tool compared to related siblings such as alphaportal_get_bus_location or alphaportal_get_student. The context is implicit from the name and description, but no explicit usage conditions or exclusions are provided.

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?

The readOnlyHint annotation already flags this as read-only, and the description reinforces that with 'List'. It goes beyond the annotation by specifying the exact return shape (id and name), which is useful behavioral context. No pagination or limits are mentioned, but for a zero-parameter, likely small dataset this is acceptable.

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

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

The description is a single, tight sentence that contains only essential information: the action, the target, and the output fields. No filler, no redundancy, and it is front-loaded with the verb. Perfectly efficient.

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

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

For a tool with no parameters, no output schema, and a simple list operation, the description covers everything an agent needs to know: what it returns and that it is a list. There is no missing context that could lead to incorrect invocation.

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

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

There are no parameters, so the schema coverage is trivially 100%. The description does not need to add parameter meaning; the baseline for zero-parameter tools is 4, and the description adequately conveys that no inputs are required by stating it simply lists grade levels.

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'), a precise resource ('district grade levels'), and explicitly names the returned fields ('id + name'). This clearly distinguishes it from sibling list tools like alphaportal_list_students or alphaportal_list_schools, leaving no ambiguity about what it does.

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

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

The description makes its purpose unmistakable: it is the tool for listing grade levels. While it does not explicitly contrast itself with alternatives, the resource name is self-selecting among the sibling tools, giving an agent a clear context for when to invoke it. It lacks explicit exclusions but none are necessary given the clarity.

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 readOnlyHint annotation already declares safety, and the description adds valuable context about what the tool returns: title, body, student, timestamp, plus a concrete example. This enriches the annotation beyond simple read-only semantics.

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

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

A single sentence that front-loads the action and resource, then efficiently appends the returned fields and an illustrative example. 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?

For a zero-parameter read-only list tool, the description fully conveys what will be returned and the scope. No output schema exists, but the enumerated fields make the return shape predictable and sufficient.

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 input schema is empty with zero parameters, so no parameter documentation is needed. Baseline for 0 params is 4, and the description appropriately mentions the scope 'account's' without inventing 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?

The description uses the specific verb 'List' with the resource 'transportation notifications' and clarifies the content type with examples. It clearly distinguishes itself from sibling alphaportal_set_notification, which is the write 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?

The description establishes that this lists the account's notifications, making the use case obvious for retrieval. It does not explicitly name alternatives or when-not-to-use, but the sibling set_notification makes the contrast clear enough.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds value by indicating that the response includes tracking numbers and status, but it does not disclose other behavioral details such as ordering, filtering, or pagination. This is adequate given the annotation coverage.

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

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

The description is a single, front-loaded sentence that states the verb, resource, scope, and key returned fields without any filler. Every element 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 tool, the description is complete: it states what is listed, the account scope, and the main included fields. The raw input schema and readOnlyHint carry the remaining operational context, so nothing needed for correct invocation is missing.

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

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

The input schema has zero parameters, so the baseline is 4. With no parameters to document, the description has nothing to add about parameter semantics, and no information is missing.

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

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

The description uses a specific verb ('List') with a clearly identified resource ('transportation requests'), scoped to 'this account'. It also mentions the returned fields ('tracking numbers and status'), distinguishing it from sibling list tools like list_students and list_notifications.

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 provides clear context: it is the tool for listing transportation requests on the account. It does not explicitly name alternatives or exclusions, but the resource is unambiguous and no sibling tool appears to overlap with this listing task.

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 readOnlyHint annotation covers safety, and the description adds behavioral context by specifying that all schools in the district are returned along with name and coordinate fields. It does not mention pagination or result limits, but for a simple parameterless list operation this is not a major gap.

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

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

The description is two short sentences with no filler. The core action and output fields are front-loaded, and the use case follows immediately.

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 listing tool, the description fully covers what the tool does, what it returns, and why an agent would use it. No output schema exists, but the description sufficiently communicates the expected 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?

The tool has zero parameters, so the description has no parameter burden. It still adds semantic value by explaining that the output can be used to resolve a school by name, which helps the agent understand the tool's purpose beyond the empty schema.

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

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

The description states a specific action ('List all schools in the district') and identifies the returned data (names and coordinates). This is unambiguous and clearly distinguishes the tool from siblings like list_students or get_bus_location.

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 provides a clear use case: 'Useful for resolving a school by name.' It does not explicitly name alternatives or exclusion criteria, but with no sibling school-listing tool, the intended usage is evident.

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 readOnlyHint annotation already assures a non-mutating operation, and the description adds meaningful behavioral context by scoping results to 'the signed-in account'. It also reveals what data is included, helping the agent set expectations. It doesn't mention edge cases like empty results, but for a simple zero-parameter list operation this is adequate.

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, purposeful sentences. The first defines the operation and outputs; the second gives actionable usage guidance. There is no redundant or vague wording.

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, this description fully covers what the tool does, what it returns, and how to use it in the broader workflow. No output schema exists, but the description names the key fields, so an agent can proceed confidently.

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 zero parameters and 100% schema coverage, there is nothing for the description to add about parameters. Per calibration, the baseline for zero params is 4, and the description correctly avoids inventing param details.

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'), a concrete resource ('students (children)'), and the relevant scope ('on the signed-in account'). It also enumerates the returned fields (grade, school, transportation flags), making the tool's purpose unambiguous. It distinguishes itself from sibling tools like get_student by clearly indicating this is the collection-level listing operation.

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' explicitly tells the agent when to invoke this tool first and why. This provides clear usage context: obtain student IDs before using per-student tools. It implies the appropriate ordering without needing to list alternatives explicitly.

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 mark readOnlyHint=true. The description adds useful behavioral context beyond that: it reveals the refresh token sources, the access-token minting attempt, and explicitly warns that no credentials are returned. This gives the agent important expectation management and protects against accidentally treating the tool as credential-returning.

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

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

The description is a single, well-structured sentence with front-loaded purpose and a concise explanation of the mechanism. Every clause adds necessary detail, and 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 no-argument, read-only status tool, the description covers the purpose, the authentication flow, and the key caveat that no credentials are returned. It does not spell out the exact success/failure return shape, but the absence of parameters and output schema makes that a minor gap for an agent deciding whether to call it.

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

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

The tool has zero parameters, so the schema fully covers parameter semantics by default. The description still adds helpful contextual information about where the refresh token comes from, though these are environment/bridge details rather than call 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?

The description clearly states a specific diagnostic action: checking whether the server can authenticate to AlphaPortal. It goes on to explain the token resolution process and access-token minting, which differentiates this from the sibling tools that handle students, buses, notifications, or 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?

The description makes the tool's context unmistakable: it is a no-argument session/authentication health check. None of the sibling tools overlap with this purpose, so no exclusions are necessary; however, the description does not explicitly say 'use when you need to verify connectivity or credentials.'

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?

Despite the annotations providing readOnlyHint=false, idempotentHint=true, and destructiveHint=true, the description goes beyond these by detailing the confirmation mechanism (both client-supported and fallback with confirmToken), the atomicity of the payload (whole set sent at once), and the risk of omitting categories being left unchanged or reset. This is significant behavioral disclosure that the annotations do not cover, such as the need for user consent and the potential side effects of omitted fields. The description does not contradict the annotations.

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

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

The description is concise at two sentences, with the primary purpose front-loaded. It efficiently packs essential information: the categories, the confirmation requirement, the fallback mechanism, and the caution about omitted categories. It could be slightly more structured, but it avoids redundancy and every sentence adds value. It earns a 4 for being appropriately sized and focused, though not perfectly organized for quick scanning.

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

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

Given the tool's complexity (nested preferences, multiple categories, confirmation logic) and the lack of an output schema, the description is complete. It covers the key behavioral aspects (confirmation, preview), the risk of omitted categories, and references MCP_CONFIRM_MODE for client-specific handling. The input schema already documents all parameters, so the description fills the gaps regarding side effects and usage flow. An agent can safely and correctly invoke this tool following the description alone.

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 input schema already has 100% coverage, with detailed descriptions for studentId, preferences (including per-category objects and their boolean toggles), confirmToken, and studentOriginalId. The description adds context about the confirmToken's usage in the two-step fallback and the preview requirement, but the schema already explains confirmToken's purpose in detail. Since the schema does the heavy lifting, the description's added value is marginal, but it does reinforce the critical behavior of confirmToken, justifying a baseline 3 rather than lower.

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 purpose: setting a student's transportation notification preferences across five specific categories, with explicit mention of push/email and AM/PM run toggles. It distinguishes itself from sibling tools like alphaportal_list_notifications (which likely reads notifications) and alphaportal_get_settings (which likely reads settings). The verb 'set' combined with the resource 'notification preferences' and the enumerated categories provides a precise and actionable definition.

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

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

The description explicitly states when to use the tool ('Set a student's transportation notification preferences') and provides crucial usage context: the need for user confirmation, the two-step fallback with confirmToken, and the caveat that omitting categories may result in unset or reset values, advising to review the preview first. It also references MCP_CONFIRM_MODE, giving the agent a clear conditional for different client capabilities. This is comprehensive guidance that leaves little to inference.

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