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

Annotations already mark destructiveHint=true, but the description adds crucial behavioral context: the confirm gate, the dry-run return of the exact payload, and the eligibility impact. This goes beyond annotations and informs the agent of the safe preview path. It does not mention the exact return format of the dry-run, but it gives enough to understand the flow.

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 short and front-loaded with the purpose. However, the 'Verified required fields' line is redundant given the schema and contains the misleading param name. Structurally, it flows well, but the error reduces its effectiveness. It is concise but not as clean as it could be.

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

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

The description covers the essential behavior (dry-run vs confirm) and the consequence (transportation eligibility). It misses details like what the response payload looks like or how the dry-run is structured, but no output schema is provided. The main gap is the parameter name inconsistency, which could cause incorrect usage. Given the complexity (3 params, mutation), it is adequate but not complete.

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

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

Schema coverage is 100%, so the baseline is 3. However, the description introduces a naming mismatch: it says 'Verified required fields: studentId, radius.' while the schema requires 'studentId' and 'radiusMeters'. This actively misinforms an agent constructing a call, potentially leading to a schema validation error. The description adds no value beyond the schema for parameter semantics and instead creates confusion.

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: 'Set a student's walk-zone radius, in meters.' It identifies the specific verb (set), resource (student's walk-zone radius), and adds the important consequence of affecting transportation eligibility. This distinguishes it from the sibling list/get tools, which are all read-only.

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 explains the confirm-gating behavior: without confirm:true it returns a dry-run, with confirm:true it executes. This tells the agent when to use the tool and how to preview changes. It does not name alternative tools, but given no sibling mutation tools exist, this is acceptable. The note about transportation eligibility implies caution.

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, as it says 'Get' and lists informational fields. It adds context about the returned data (e.g., server date) beyond the annotation, but does not describe authorization or rate limits, which is acceptable given the read-only nature.

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, concise sentence that states the purpose and key return fields without redundant language. It is well-structured and front-loaded.

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

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

For a simple read-only tool with no parameters and no output schema, the description provides sufficient context about what will be returned. It names the specific data fields and includes the server date, making it complete for an agent to call correctly.

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

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

The tool has zero parameters, so the description correctly omits parameter details. The empty schema covers 100% of parameters, and the description adds no param semantics, but none are needed.

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

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

The description clearly identifies the tool's purpose: retrieving account/school district information including name, timezone, date/phone formats, and current server date. It uses a specific verb 'Get' and clearly distinguishes this from siblings like alphaportal_get_profile, which likely focuses on user-level data.

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

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

The description implies usage when account-level information is needed, but it does not explicitly contrast with sibling tools or state when not to use it. There is no mention of alternatives or exclusions, so the guidance is implicit rather than explicit.

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

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

The annotations declare readOnlyHint=true, and the description adds meaningful behavior beyond that: it returns the last known position and returns empty when the bus is not running. This helps set expectations about freshness and empty results, which is valuable for a real-time location tool.

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

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

The description is a single sentence that front-loads the core purpose, includes the key returned fields, and adds the empty-state behavior. No words are wasted, and every clause adds distinct value.

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

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

For a simple two-parameter read-only tool with no output schema, the description is complete: it states the inputs (student/run), the output fields, and the edge case of the bus not running. The schema covers the remaining required details, and annotations confirm no side effects.

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

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

Schema description coverage is 100%, so the baseline applies. The description's mention of 'selected run (AM or PM)' reinforces the shift parameter semantics, and 'student's bus' aligns with studentId, but it does not add new details beyond what the schema already documents.

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 precise verb ('Get') and resource ('live GPS location of a student's bus'), explicitly enumerates returned fields (latitude, longitude, speed, vehicle id), and scopes the operation to AM/PM runs. This clearly distinguishes it from all sibling getters, which retrieve profiles, students, settings, or reports.

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 clearly indicates when this tool is appropriate: when the agent needs the current GPS position of a student's bus for a specific run. It does not name an alternative or explicit when-not-to-use condition, but no sibling tool offers similar bus-location functionality, so the context 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?

The annotation readOnlyHint=true already signals a safe read operation. The description reinforces this with 'Get' and adds valuable context by listing the exact fields returned, which goes beyond the annotation's generic hint. No contradictory behavior is mentioned.

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, concise sentence with no fluff. The resource and its key fields are front-loaded, and every word contributes to understanding the tool's purpose.

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 tool with no output schema, the description fully covers what an agent needs to know: what the tool does, what it returns, and that it's read-only (reinforced by the annotation). No additional detail is required to invoke it correctly.

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

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

The tool has zero parameters, so the schema already fully covers the input space. The description is not required to add parameter semantics; the baseline of 4 applies as there is nothing to improve.

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 a well-defined resource ('signed-in user profile'), and enumerates the exact fields returned (name, email, role, account). The resource is clearly distinct from sibling tools like alphaportal_get_account or alphaportal_get_settings, so an agent can disambiguate without opening schemas.

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

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

The description clearly implies when to use this tool: whenever the agent needs the current user's own profile data. It doesn't explicitly state when not to use alternatives, but the scoping ('signed-in user') makes it obvious that this is the right choice for self-profile requests, while siblings target other resources (notifications, settings, students, etc.).

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 mark readOnlyHint=true, and the description adds meaningful behavioral detail beyond that: the link is one-time, downloadable as PDF, and intended to be opened in a browser. This gives an agent realistic expectations about the result without contradicting the annotations.

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

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

Two short sentences deliver the core behavior and return type with no filler. The action, resource, scope, and result are front-loaded.

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

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

For a simple, one-parameter read-only tool with no output schema, the description is sufficient: it specifies the input via the schema, the output as a URL, and the nature of the link as one-time and browser-openable. Nothing critical is missing.

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

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

Schema coverage for the single parameter is 100%: studentId is already documented as numeric and sourced from alphaportal_list_students. The description adds no additional parameter detail, but with full schema coverage, a 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 names a specific action ('Get'), a precise resource ('one-time PDF download link'), and scopes it to a student's transportation report with content hints (stops, schedule). This clearly separates it from sibling tools like alphaportal_get_student_stops, which return data rather than a one-time browser URL.

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

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

The use case is clear: call this when a downloadable PDF of a student's transportation report is needed. It does not explicitly discuss when-not-to-use or name alternative sibling tools, so it stops just short of a top score.

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 provide readOnlyHint: true, so the read-only nature is disclosed. The description adds useful context beyond that by specifying what the settings contain (notification types and features). It does not contradict annotations and provides additional meaning regarding the tool's output scope.

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, succinct sentence that leads with the action and resource. The parenthetical clarifies scope without redundancy. Every word earns its place; no filler or unnecessary detail.

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

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

Given the tool has no parameters, no output schema, and annotations cover safety, the description provides enough context for an agent to know what it returns (portal settings) and its scope (district). It could potentially mention the output format, but this is minor since the name and description make the purpose clear.

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 is trivially complete. Per calibration, a baseline of 4 applies; the description does not need to add parameter information since there are none. It does explain the purpose of the returned data, which is sufficient.

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 verb ('Get') and resource ('portal feature/visibility settings'), and further clarifies it refers to 'which notification types and features are enabled for this district.' This distinguishes it from sibling tools like alphaportal_set_notification (which modifies settings) and alphaportal_list_notifications (which likely lists 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 implies usage ('when you need to know which features are enabled') but does not explicitly state when to use it over alternatives or when not to use it. Since it is a simple getter with no parameters, the guidance is adequate but not explicit about alternatives or exclusions.

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

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

The readOnlyHint annotation already covers the safety profile. The description adds useful behavioral context by naming what the result includes, but it does not address empty results, permissions, or data source. With annotations carrying the read-only burden, this meets the baseline.

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

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

One sentence with no filler, front-loading the action and resource, then enumerating the included details. Every word contributes meaning.

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 well-documented parameter, the description gives enough contextual detail about the result scope. It does not promise an exact return structure, but given low complexity and no output schema, the description is adequately complete.

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

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

The schema fully documents the single studentId parameter, including its type and that it comes from alphaportal_list_students. The description adds no additional parameter-level detail beyond the schema, 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 uses a specific verb and resource: 'Get a student's full transportation detail,' then lists the concrete contents (assigned school, morning/afternoon stops, times, calendars). This clearly distinguishes it from sibling alphaportal_get_student_stops, which likely covers only 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 explicit when-to-use or when-not-to-use guidance. The phrase 'full transportation detail' implies use when the complete picture is needed, and the sibling name alphaportal_get_student_stops hints at a stops-only alternative, but the routing is left to inference rather than stated.

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

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

Annotations already declare readOnlyHint: true, so the description does not need to state read-only behavior. The description adds the specific data returned (stop fields), which is contextual but not strictly behavioral. It does not disclose any side effects, authentication requirements, or rate limits, though read-only tools typically have minimal behavioral concerns.

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, focused sentence that leads with the verb and resource, then lists the return fields. There is no filler or redundancy; it earns its place entirely.

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

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

With no output schema present, the description appropriately enumerates the return fields and implies multiplicity ('for each'). It does not specify the container type (e.g., array) or error cases, but for a low-complexity read-only tool with a single parameter, this is sufficient. The fields listed are comprehensive and unambiguous.

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 has 100% description coverage for studentId, including its source (alphaportal_list_students). The description adds no extra information about the parameter's format, constraints, or usage beyond what is already in the input schema, so it does not compensate beyond the baseline for high coverage.

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 verb 'Get', the resource 'a student's assigned bus stops', and enumerates the return fields (stop name, scheduled time, days, location). This distinguishes it from siblings like get_bus_location (live tracking) and get_student (basic profile) without ambiguity.

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

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

The description implies when to use it (to fetch a student's assigned stops) but does not explicitly contrast it with alternatives or specify when not to use it. For instance, it does not mention that get_bus_location should be used for real-time bus tracking instead. The reference to studentId from alphaportal_list_students implies a prerequisite but no exclusions.

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

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

The readOnlyHint annotation already covers the read-only nature, so the description does not need to restate it. However, the description adds no behavioral context beyond the basic list operation – no mention of ordering, filtering, pagination, or any side effects. Given the annotation covers safety, the description adds almost no value beyond the name.

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, compact sentence with the action upfront and the expected output clearly stated. Every word earns its place, and there is no redundancy 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?

For a zero-parameter, read-only list tool with no output schema, the description adequately specifies the returned fields (id + name). It lacks usage context but within its scope it is complete enough for correct invocation. A slightly richer note on when to use it would push it to 5, but it is not deficient.

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, and schema coverage is 100%, so the baseline is 3. The description does not need to add parameter details because there are none. It correctly omits any parameter explanation, which 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 explicitly states the verb 'List' and the resource 'district grade levels', and specifies the returned fields (id + name). It is immediately clear what the tool does and distinct from siblings like list_schools or list_students, which target different resources.

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 that this tool is used when one needs grade level information, but it does not explicitly contrast it with alternatives or state when not to use it. No mention of exclusions or preferred contexts, so it relies on the agent's inference from the resource name.

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

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

Annotations declare readOnlyHint=true, and the description's 'List' is consistent. The description adds useful context about return content (title, body, student, timestamp) beyond the annotation, though it does not mention auth, rate limits, or ordering—minor for a read-only list.

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?

Single sentence, front-loaded with the action, then specific details. No unnecessary words 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 simple read-only list with no parameters and no output schema, the description sufficiently specifies what notifications are returned and their fields (title, body, student, timestamp). It omits mention of ordering or pagination, but these are not critical for a no-parameter retrieval tool.

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

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

Tool has zero parameters, so the baseline is 4 per the rubric. The description's mention of the returned fields provides contextual value but does not need to explain parameters since none exist.

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

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

States a specific verb (list), resource (account's transportation notifications), and clarifies the content (arrival/departure alerts with fields). Distinguishes from siblings by focusing on notifications rather than students, schools, or other resources.

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?

Purpose is clear enough that an agent knows when to call this tool—whenever notifications need to be retrieved. No explicit alternatives are mentioned, but the context is unambiguous given the sibling set, and no conflicting tool serves the same purpose.

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

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

The annotations already declare readOnlyHint=true, and the description does not contradict that. It adds useful context about account scope and the presence of tracking numbers and status in the results, but it does not disclose any additional behavior such as pagination, ordering, or filtering limits.

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 concise sentence that states the action, the resource, and the useful output fields. There is no filler or repetition, and the key information is front-loaded.

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

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

For a read-only, zero-parameter list operation, the description is complete: it identifies the resource, the scope ('on this account'), and the output contents ('tracking numbers and status'). No output schema exists, but the description covers the return essentials sufficiently.

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

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

The tool has zero parameters and the schema description coverage is 100%, so the schema fully documents everything needed. The description appropriately adds no redundant parameter explanations, which matches the baseline for a parameterless tool.

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

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

The description names a specific verb ('List'), a clear resource ('transportation requests'), and the key output fields ('tracking numbers and status'). It is distinct from siblings like list_notifications and list_students because the resource is unambiguously transportation requests.

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: whenever the agent needs to see transportation requests submitted on the account. However, it does not explicitly state when not to use it or mention alternative tools such as list_notifications or the various get_* tools, so the guidance is only implicit.

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 signals a safe read operation. The description adds value by disclosing the returned fields (names and lat/lng coordinates). It does not contradict the annotation and provides enough behavioral detail for a simple list tool.

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

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

The description is two short sentences with no filler. The core action is front-loaded, and the secondary note about resolving by name is valuable context.

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 parameterless, read-only list tool with no output schema, the description is complete: it names the resource, the output fields, and the main use case. Nothing essential is missing.

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

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

The tool has zero parameters, so there is no parameter semantics burden on the description. The schema has no properties, and the description appropriately explains what the tool returns instead.

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') and resource ('schools in the district'), plus what is returned (names and coordinates). It is clearly distinguishable from sibling tools such as alphaportal_list_students and alphaportal_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 gives a clear use case: 'Useful for resolving a school by name.' This implies when an agent should call it, though it does not explicitly discuss alternatives or situations where it should not be used.

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 the safety profile, so the description doesn't need to restate non-destructiveness. It adds value by disclosing the return fields (grade, school, transportation flags) and the purpose of retrieving studentId. However, it doesn't provide deeper behavioral context like pagination or data freshness—acceptable given 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 two short sentences with no filler. The action is front-loaded, and the second sentence adds a clear directive for use. Every word earns its place.

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

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

For a zero-parameter, read-only listing tool with no output schema, the description covers everything an agent needs: the exact scope, the fields returned, and the primary use case. No critical information is missing.

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

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

The tool has zero parameters, so the schema is trivially complete. Per the calibration baseline for 0 params, the description doesn't need to explain parameters, and no gaps exist.

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

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

The description clearly states the action ('List'), the resource ('students (children) on the signed-in account'), and specific attributes ('grade, school, and transportation flags'). This distinguishes it from sibling list tools like list_schools or list_grades, and from get_student, which targets a single student.

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 instruction 'Start here to get each studentId' explicitly frames this as the entry point for student-related workflows, giving clear context on when to use it. It doesn't explicitly name alternatives or exclusions, but the usage context is strong enough to guide an agent.

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 explicitly notes that it returns no credentials, and it details the token resolution sources (env var, saved session, browser bridge). This adds meaningful behavioral context beyond the readOnlyHint annotation, which already indicates non-destructive behavior. No contradictions.

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 (two sentences), front-loaded with the core purpose, and each clause adds value. It is well-structured and avoids unnecessary elaboration.

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 low complexity, no parameters, and no output schema, the description fully covers what an agent needs: what it checks, how it resolves the token, and that it returns no credentials. No gaps remain 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 tool has zero parameters, so the schema is trivially covered. Per the baseline for 0 params, a score of 4 is appropriate. The description doesn't need to explain parameters since none exist.

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

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

The description clearly states the tool's purpose: checking whether the server can authenticate to AlphaPortal by resolving a refresh token and attempting to mint an access token. It distinguishes itself from sibling data-access tools by focusing on session status rather than resource retrieval.

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

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

The description implies usage (check authentication status) but does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. Sibling tools are all data access, so the purpose is distinct, but the lack of explicit guidance prevents a higher score.

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 goes beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing the dry-run behavior, the confirm requirement, and the risk of omitted categories being reset. This is thorough coverage of the tool's actual side effects and safety nuances.

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

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

Two sentences with no waste: the first sentence states the purpose and scope, the second explains the confirm gate and a critical caveat. Information is front-loaded and immediately actionable.

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

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

Given the tool's complexity (nested objects, confirm gate) and no output schema, the description covers the essential behaviors (dry-run, risk of omission). It does not state what a successful confirm returns, but that is likely implicit. The description is sufficiently complete 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% for all parameters, so the schema already documents each field. The description adds context by listing the categories, explaining the confirm parameter's role, and warning about the whole-preference-set behavior, which is extra value beyond the schema.

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

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

The description clearly states the verb 'Set' and the resource 'student's transportation notification preferences', and enumerates the exact categories it affects. This distinguishes it from sibling tools like alphaportal_list_notifications, which would be list operations.

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 explains the confirm gate and dry-run behavior, telling the agent to use confirm:true to actually apply changes and review the dry-run first. However, it does not contrast with alternatives like list_notifications, but the primary usage condition is clearly stated.

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