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

Annotations already flag the operation as destructive and not read-only. The description adds valuable context: confirm-gating, dry-run behavior without confirm:true, and the consequence for transportation eligibility. This goes beyond what annotations provide.

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

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

Two sentences, with the core purpose front-loaded and the confirm-gating behavior following closely. It is appropriately sized, though the 'Verified required fields' note is somewhat redundant with the schema and contains the minor field-name inconsistency.

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, confirm-gated mutation, the description covers the key operational aspects: the gate, the dry-run behavior, and the real-world impact. It doesn't explicitly state what happens when confirm:true is passed, but that is clearly implied. No output schema exists, so return-value details are not expected.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minimal semantic value over the schema, mostly restating units and required fields. The use of 'radius' in the description instead of the schema's 'radiusMeters' is slightly imprecise but not misleading.

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 ('Set') and a concrete resource ('student's walk-zone radius, in meters'), making the tool's function immediately clear. It is easily distinguished from the sibling read/list/get tools.

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 usage context is implied by the action ('Set a student's walk-zone radius') rather than explicitly stated. No alternatives are named and there is no when-not-to-use guidance, but the confirm-gating note hints at the intended workflow.

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?

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?

Annotations only set readOnlyHint=false and destructiveHint=false, which are vague. The description substantially enriches behavioral disclosure: it explains the confirm-gated dry-run (without confirm:true it returns a preview), the fact that the portal sends the entire preference set at once, and the risk that omitted categories may be left unchanged or reset by the server. It explicitly advises reviewing the dry-run first. This is exactly the kind of context the annotations do not provide, and it is accurate and non-contradictory.

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 long with zero filler. The first sentence states the purpose and lists categories; the second delivers the critical confirm-gating and whole-set warning. It is front-loaded with the core action and the most important caveat. 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 tool with nested objects and multiple categories, the description covers the essential behavioral aspects: dry-run confirmation, whole-set semantics, and the caution about omitted categories. It does not describe return values, but there is no output schema, so the agent is left guessing what the response looks like. However, the description's warnings about reviewing the dry-run likely imply the response includes a preview payload. Given the complexity, it is nearly complete, but a brief note on response format would make it 5.

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

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

Schema coverage is 100% (every parameter and nested property has a description), so the baseline is 3. The description adds meaningful context beyond the schema: it clarifies that the categories are those 'the district enables' and, more importantly, explains the whole-set behavior (omitted categories may be left unchanged or reset). It also reiterates the confirm gating, though that is already in the schema. The added nuance about district enablement and the reset risk elevates this to 4.

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 sets a student's transportation notification preferences, explicitly naming all five categories (stopRadiusEntry, studentScan, backupBus, schoolArrival, stopServiced). It uses a specific verb ('Set') and resource, and it stands apart from sibling read/list tools like alphaportal_list_notifications, which is the obvious alternative. The scope is unambiguous.

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 (to modify preferences) versus listing them (via alphaportal_list_notifications), though it does not explicitly name that sibling. It provides a crucial usage guideline: the confirm-gated dry-run behavior and the warning to review the dry-run first, which helps the agent avoid unintended writes. It also explains the whole-set semantics, which is key for correct invocation. A brief mention of the alternative would push this to 5.

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