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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that classes are created hidden, which is a significant side effect, and notes the PS_ENABLE_WRITES requirement. While it does not cover all possible side effects (e.g., failure modes), it provides meaningful, non-obvious behavior that an agent needs to know before 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 compact and well-organized. The key behavioral point (hidden status) is stated upfront, followed by essential follow-up actions, and then a clean bulleted argument list. No filler or repetition; every sentence adds 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?

Given the tool's complexity, the description covers the essential purpose, the hidden-creation behavior, the permission requirement, and next steps. An output schema exists (per context signals) which presumably documents return values. The description is complete enough for an agent to invoke it correctly without additional inference, though it could mention error handling or default values for omitted parameters (e.g., nothing about what happens if grade_ids is empty). Overall, it is robust.

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 0%, so the description must compensate for all three parameters. It briefly describes each parameter (school_id, name with an example, grade_ids with source list_grades). This adds value beyond the bare schema, although school_id could be more explicit about its source, and grade_ids could mention that multiple IDs are allowed in the array. Still, it sufficiently disambiguates the parameters.

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

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

States a clear verb (create) and resource (class/section) at a school, with specific scope. It also differentiates from related siblings by explaining that new classes are hidden and need further steps (set_class_visibility, add_class_staff). An agent can easily identify this is for creating a brand-new class, not editing or managing existing ones.

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 creating a new class) and gives essential follow-up actions (calling set_class_visibility and add_class_staff). It does not explicitly name alternatives like edit_class or set_class_visibility as 'use instead,' but the workflow context is clear enough for correct selection among siblings.

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

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

With no annotations, the description carries the full burden and delivers thoroughly: it explains that existing staff are preserved, duplicates are skipped, role changes occur, room parents are guardians, and it warns about concurrency risks. It even details the internal read-then-write sequence, making the behavior highly predictable.

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 substantial but each sentence earns its place. It uses clear section headers (SAFETY, args) and front-loads the core purpose. The safety warning is detailed yet necessary due to the serious consequence of concurrent writes. The structure aids scanning and comprehension without 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?

Given the tool's complexity (4 params, write operation, delicate concurrency), the description covers all operational aspects: prerequisites, sourcing IDs, behavior on existing data, safety constraints, and parameter details. Nothing critical is missing; the output schema likely handles return format, so the description's scope is appropriate.

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 0%, so the description compensates completely. Every parameter is explained: section_id sources from list_classes, user_ids from list_staff/list_parents, role enumerates valid values, and class_title explains its default behavior. This gives the agent everything needed to populate arguments correctly.

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 opens with a specific action: 'Assign teachers, assistants, or room parents to a class.' This clearly identifies the verb, resource, and role types, and distinguishes it from sibling tools like remove_class_staff or add_class_students. The mention of 'class-staff write' further clarifies the domain.

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 states the prerequisite 'Requires PS_ENABLE_WRITES' and explains when not to use in parallel with remove_class_staff, citing the risk of data loss. It also points to list_staff and list_parents for sourcing user IDs. However, it does not explicitly enumerate alternative tools for different actions (e.g., when to use remove_class_staff), leaving some inference to the 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?

With no annotations, the description must carry the full behavioral burden. It does so by stating the permission requirement ('Requires PS_ENABLE_WRITES'), the concurrency constraint ('Never call ... in parallel ... use one call at a time'), and the side-effect guarantees ('without disturbing the students already in the class or their other classes'). It also notes idempotency, which is crucial for safe re-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 moderately long but well-structured with a safety header, behavior explanation, usage example, and arg list. Every section serves a purpose, and the safety warning is front-loaded. It is not bloated; the extra length is justified by the complexity of the write operation.

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 tool's function, permission needs, idempotency, concurrency constraints, and parameter sourcing. Given the operation's complexity and the presence of an output schema (which presumably documents return values), this is nearly complete. It might note failure modes, but that is a minor omission.

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 0%, so the description must add meaning. It provides explicit arg descriptions: 'section_id: Class/section ID (from list_classes)' and 'student_ids: One or more student IDs (from list_students)'. This goes beyond the schema's type/title and tells the agent exactly where to obtain valid inputs, which is high-value guidance.

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 opens with 'Enroll students in a class,' a specific verb plus resource that clearly distinguishes it from siblings like list_class_students or remove_class_students. It avoids tautology and names the operation precisely.

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 concrete use case: 'To assign a whole grade at the start of the year, call this once per classroom with that classroom's students.' It also explains idempotency ('Students already enrolled are skipped, so re-running is safe') and warns about parallel calls. It does not explicitly mention alternatives, but the context is sufficient for an agent to decide when to use it.

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

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

With no annotations, the description carries the full burden. It discloses a key behavioral trait: 'The new user id is not returned — call list_students or the parent roster afterward.' It also states the invariant that a parent is always created attached to at least one student. This is valuable context beyond what the schema provides, though it does not discuss failure modes or reversibility.

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 and well-structured: a clear purpose sentence, a requirement note, a behavioral note, and a clean Args list. Every sentence earns its place, and the critical information is front-loaded. No fluff 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?

Given that an output schema exists (though not shown), the description need not explain return values; it even goes beyond by stating what is NOT returned. It covers required permissions, the attachment constraint, and the follow-up action. It lacks error cases or idempotency details, but for a create operation with clear inputs, this is sufficiently 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 0%, so the description must compensate. It lists each parameter with a brief description, notably clarifying that student_id is from list_students and that email/phone are optional. This adds meaning beyond the bare schema names and default nulls, though it could be more detailed about format constraints (e.g., phone format).

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: 'Create a guardian/parent and link them to a student.' This specific verb+resource distinguishes it from siblings like edit_parent, link_guardian_to_student, and invite_parent, which handle different aspects of parent management.

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 for usage: it requires PS_ENABLE_WRITES, always attaches to a student, and instructs to get student_id from list_students. It does not explicitly mention when to use an alternative tool (e.g., link_guardian_to_student for existing parents), but the conditions are implied strongly enough for an agent to infer the right usage scenario.

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?

No annotations are provided, so the description carries the full burden. It discloses the permission requirement, the email invite side effect, and the behavior that section_ids assignments are made directly, contrasting with ParentSquare's own behavior. It also notes that email is needed for registration. While it doesn't cover all edge cases, it gives strong behavioral context.

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 front-loaded with purpose and a permission note, then a well-structured bullet list of parameters. Each sentence adds value. It is somewhat long due to the parameter list, but that is justified given the tool's complexity. No fluff.

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 10 parameters, no annotations, and 0% schema coverage, the description covers the core behavior, permissions, side effects, and each parameter meaning. It does not discuss return values (though an output schema exists) or potential errors/edge cases (e.g., duplicate emails, missing email consequences), but overall it is thorough enough for an agent to correctly invoke the tool.

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

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

Schema description coverage is 0%, so the description is the only source of parameter meaning. It provides an 'Args:' section explaining all 10 parameters, including optionality, defaults, and hints like 'from list_classes' for section_ids. This fully compensates for the lack of schema descriptions.

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 ('Add') and resource ('a teacher or other staff member to a school') with clear scope. It distinguishes itself from sibling tools like add_student and add_parent by specifying staff, and also unique behavior with section_ids. The purpose 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?

Provides some context (requires PS_ENABLE_WRITES, mentions when section_ids should be used) but does not explicitly name alternatives or conditions for when not to use this tool. It could mention add_class_staff for adding existing staff to classes, but it doesn't. Guidance is mostly 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?

No annotations exist, so the description carries the full disclosure burden — and it excels. It reveals the PS_ENABLE_WRITES permission requirement, the fact that the new student id is not returned (requiring a follow-up list_students call), that the roster is read back after writing so the result reflects actual existence, and the non-obvious 5xx hazard where the error page is rendered after save so the record may exist and no delete route prevents duplicates. This is exactly the behavioral detail an agent needs.

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

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

The description is long but every sentence earns its place: purpose, auth, prerequisite, post-return behavior, error semantics, and a structured Args block. Critical operational warnings are front-loaded before the parameter list, and the Args section adds value because the schema provides zero descriptions. It is dense rather than padded, though it borders on verbose.

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

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

For a 5-parameter mutation with no annotations, this is complete: purpose, permission requirement, pre-call workflow, post-call retrieval, return semantics (roster read-back), error/duplication behavior, and all parameter meanings are covered. An output schema exists, so the description rightly does not restate return structure. Nothing an agent needs to invoke this safely and correctly 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 description coverage is 0% — every parameter's meaning must come from the description, and it does. Each of the five args gets a one-line definition: school_id, first_name, last_name, grade_id (with the source list_grades noted), and student_sis_id (marked Optional with its purpose as an SIS/external ID). This fully compensates for the empty schema and adds provenance that the schema cannot express.

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 opening sentence, 'Create a new student on a school's roster,' uses a specific verb (create) and a precise resource (student/roster). This clearly distinguishes it from write-siblings like edit_student (mutation vs creation) and read tools like list_students, and from add_parent/add_class_students which target different resources. A sibling differentiation is achieved by the create-verb paired with the roster resource.

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 prerequisite workflow: use list_grades(school_id) to find the grade_id before calling, and call list_students afterward to retrieve the new id. It also transmits a crucial retry rule (do not retry on a 5xx alone). It does not explicitly mention when not to use this tool in favor of alternatives (e.g., add_parent or add_class_students), but the create-a-roster-student context is unambiguous given siblings, so the omission is minor.

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

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

With no annotations, the description carries the full disclosure burden. It explains that each unregistered guardian receives an email/text invite, that already-registered users are automatically skipped, and that the return message reports how many were actually notified. This is strong transparency, though it could also mention potential side effects like cost per message or rate limits, so a 4 is warranted.

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

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

The description is organized with a clear lead, prerequisites, behavior, and input sourcing. It is slightly verbose in places (e.g., repeating 'from list_parents'), but it front-loads the purpose and keeps each sentence informative. The structure supports quick comprehension.

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 moderate complexity (2 params, output schema exists), the description covers all necessary aspects: purpose, prerequisites, behavioral nuance (skip logic, return count), and how to obtain valid inputs. The output schema is presumably available to detail the return format, so nothing critical is missing for an agent to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate. It adds meaningful context: `user_ids` are specifically the guardian IDs from `list_parents`, and the tool skips already-registered ones, making it clear that passing registered IDs is safe. While it doesn't delve into array size limits or type formats, it provides enough beyond the raw schema for correct invocation.

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 opens with a clear, specific action: 'Send registration invitations to multiple guardians at once.' It identifies the resource (guardians) and distinguishes itself from the singular `invite_parent` sibling by emphasizing 'multiple' and 'at once.' The behavior of skipping registered users further clarifies its scope.

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

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

It explicitly states a prerequisite (PS_ENABLE_WRITES) and provides a concrete workflow: obtain user_ids from `list_parents(school_id)`, typically those with `registered=false`, including the 'invite all' pattern. This is actionable guidance for when to use the tool and how to source inputs, clearly differentiating it from alternatives.

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?

No annotations present. Description states return value (local file path) and that it saves to disk. Could mention side effects or permissions, but adequate for a download operation.

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?

Concise with clear structure: purpose, return, usage, args. Could be slightly more compact, but effective.

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?

Returns local path (output schema exists). Explains source of URLs. Covers essential context for a download tool.

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

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

Schema description coverage is 0%, but description fully explains both parameters: url (source) and filename (optional, defaults to original). Adds meaning beyond 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?

Clearly identifies the action (download) and resource (photo/video/file to local disk from URL). Differentiates from sibling tools that list files.

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

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

Explicitly states when to use: 'Use URLs from list_photos, list_files, or get_post attachment results.' Provides clear context for usage, but no explicit when-not-to-use.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the permission requirement, describes the replace-then-read-back behavior ('current values are read back from the class first and resent'), which reveals that omitted fields are preserved rather than cleared. It also clarifies that staff are unaffected, preventing misuses. This is thorough for a mutation 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 well-structured and front-loaded: it opens with purpose and permission, then explains behavioral nuances, and ends with a clear argument list. Every sentence adds value—the permission note, the replace semantics, and the staff exclusion are all critical. The parameter documentation is necessary given the empty schema, and the overall length is justified.

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 five parameters, the replace-send behavior, permission requirements, and sibling interactions, the description covers all essential operational details. It explains when to use alternative tools, what each parameter does, and the underlying endpoint's behavior. The presence of an output schema means return values need not be described, and 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?

Schema description coverage is 0%, so the description must fully document parameters. The 'Args' section explains each parameter's meaning, optionality, and special behavior (e.g., grade_ids 'replaces the current grades' and room example 'Room 5'). This fully compensates for the absence of schema descriptions, leaving no ambiguity.

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: 'Rename a class or change its room code / grades.' It also distinguishes itself from sibling tools by explicitly stating that staff are not affected and directing to add_class_staff / remove_class_staff for those operations. This provides a specific verb and resource, and differentiates from related mutation tools like add_class and set_class_visibility.

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 explicit usage guidance by noting that staff changes are out of scope and referencing alternative tools. It also explains the partial-update semantics ('Only provided fields change') and the permission requirement (PS_ENABLE_WRITES), which informs when the tool is appropriate. This is clear and actionable for selecting between tools.

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

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

With no annotations, the description carries the full burden. It discloses the PS_ENABLE_WRITES permission requirement and the partial-update semantics ('Only provided fields change; existing student links are preserved'). This adds meaningful behavioral context beyond the schema, though it does not mention side effects like reversibility or response format.

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 well-structured with a clear purpose sentence, permission note, behavioral note, and a parameter list. It is somewhat repetitive since param details could be inferred from schema, but the semantic additions justify the length. Front-loaded with the main action.

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 6 parameters, an output schema, and no annotations, the description adequately covers the essentials: purpose, permission, partial update, and prerequisite. It does not mention error handling or what the response contains, but the output schema presumably covers return values. Overall sufficient 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 coverage is 0%, so the description must compensate. It lists each parameter with a short explanation, notably clarifying that user_id comes from list_parents. This adds value beyond the raw schema, though it does not detail formats for phone/email or examples, which would be helpful.

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 'Update a guardian's name, email, or phone' which clearly identifies the verb (update), resource (guardian), and the specific fields affected. This distinguishes it from sibling tools like add_parent (create) and list_parents (read) 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?

It gives explicit prerequisite guidance: 'Get the user_id from list_parents(school_id)' and clarifies partial update behavior. It does not explicitly state when not to use this tool or name alternatives like add_parent or invite_parent, but the context is clear enough for an agent to route correctly.

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

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

With no annotations provided, the description carries the full burden and excels: it discloses partial-update semantics ('Only provided fields change... STAFF/ADMIN access level — is left untouched'), the PS_ENABLE_WRITES permission requirement, and the guardian rejection behavior. This is rich behavioral context for a mutation tool that annotations would normally be expected to cover.

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?

Well-ordered and front-loaded: the core purpose leads, then the critical permission prerequisite, then the partial-update behavior, then alternative routing, ending with the compact arg list. Every sentence contributes; the permission and exclusion notes are the highest-value info and appear early.

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 mutation tool with 8 params and 0% schema coverage, this is complete: it covers the permission gate, k part updates, parameter sourcing, sibling alternatives, and an error case (guardians). An output schema exists to carry return-value details, so the description doesn't need to explain them. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does by listing all 8 args with inline semantics. It adds real value for title (with an example) and staff_id ('The school's own staff/external ID'), clarifying the distinction from user_id. However, several parameter descriptions are terse restatements ('New first name', 'School ID') that don't add meaning beyond the schema, keeping it a notch below perfect.

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 ('Update a staff member's name, email, phone, title, or staff ID'), enumerating the exact fields affected. It differentiates from siblings by explicitly naming edit_parent as the tool for guardians, and add_class_staff/remove_class_staff for class assignment changes.

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?

Excellent routing guidance: names PS_ENABLE_WRITES as a prerequisite, tells the agent to get user_id from list_staff(school_id), explicitly says class-assignment changes should go through add_class_staff/remove_class_staff, and states that guardians are rejected and to use edit_parent for those. Nothing is left 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?

With no annotations provided, the description carries the full behavioral disclosure burden. It clearly explains that only passed fields are changed, current values are preserved for unspecified fields, and class enrollment is untouched. It also notes the required flag. This is comprehensive for a mutation tool, covering partial-update semantics and side effects.

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 well-structured: a one-line purpose statement, a behavioral paragraph, and a concise Args list. It is efficient without waste, though slightly longer than strictly necessary; every sentence contributes meaning. Front-loading the purpose and key behavioral rules is effective.

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 (6 params, partial update, no annotations), the description covers all necessary context: the write flag, source of IDs, alternative tools for class enrollment, and update semantics. An output schema exists, so not describing return values is acceptable. Nothing essential 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?

Schema description coverage is 0%, so the description must explain each parameter. It lists all six parameters with meaningful annotations: school_id and student_id are identified as identifiers (with student_id sourced from list_students), and optional fields are labeled 'New ... (optional)' with grade_id sourced from list_grades. This adds real semantic value beyond the raw 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 opens with 'Update an existing student' which is a specific verb+resource, and immediately clarifies partial-update semantics ('Only provided fields change'). It also differentiates from sibling tools by explicitly stating 'Class enrollment is never touched' and naming the class-management alternatives, making the tool's scope clear.

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 explicit when-to-use and when-not-to-use guidance: it states the write flag prerequisite ('Requires PS_ENABLE_WRITES'), specifies that class enrollment is handled by other tools, and names those exact alternatives (add_class_students, remove_class_students, move_student_to_class). This gives an agent direct routing instructions.

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?

Discloses return format (JSON array with fields) and a limitation (no events for image/PDF calendars). However, no annotations exist, and description does not mention read-only nature, auth requirements, or side effects. Could be more transparent.

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?

Description is well-structured with a clear first sentence, return info, and fallback note. Slightly wordy with the 'Args:' line, but overall efficient 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?

Given no output schema, description covers return format and a practical limitation. Missing error handling and prerequisites, but for a single-param tool, it provides adequate context for usage.

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

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

Only parameter 'school_id' is listed with a basic 'School ID' line. The schema provides no description (0% coverage), and the description adds no extra meaning like how to find the ID or valid values. Minimal value beyond 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?

Description clearly states the tool gets calendar events for a school using ICS export. It distinguishes from siblings by noting that some schools use images/PDFs instead and directs to get_feeds/get_post as alternatives.

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

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

Explicitly says when to use (to get calendar events) and when not (schools using images/PDFs). Provides clear alternative workflow using get_feeds and get_post, aiding agent decision-making.

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?

No annotations are provided, so the description carries full burden. It discloses that the tool returns staff entries with user_id and assoc_id, and implies a read operation via 'Get' and the pre-change usage. However, it doesn't explicitly confirm it's read-only, nor does it mention error handling, permissions, or missing-ID behavior. This is adequate but not comprehensive.

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 efficiently structured: the main purpose in the first line, followed by staff entry details, a usage note, and a parameter description. It's slightly longer than necessary but every sentence adds value. Front-loading the purpose ensures quick comprehension.

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 get operation, the description covers the essential elements: what it returns (staff list with fields), when to use it (before staff changes), and the parameter. It doesn't describe return format beyond staff entries, but an output schema exists (though not shown) which may cover that. Minor omissions like error behavior are not critical for this simple 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?

The schema describes section_id as an integer, but the description adds crucial meaning: 'Class/section ID (from list_classes)'. This tells the agent where to obtain the value and what it represents, going beyond the bare type definition. Given 0% schema description coverage, this compensation is valuable.

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 'Get one class with its full staff list' – a specific verb and resource. It details the staff categories (teachers, assistants, room parents) and distinguishes this from list_classes (which lists all classes) and other class-related tools. The purpose 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 gives a clear usage directive: 'Use this before changing staff to see the current state.' This tells the agent when to invoke it. It doesn't explicitly exclude other scenarios or name alternative tools, but the context is specific enough that the agent understands this is for inspecting a single class prior to modifications.

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?

No annotations provided, so description carries full burden. It only states 'Read' indicating read-only nature but lacks details on auth requirements, rate limits, or output structure beyond 'all messages'. More transparency needed.

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 with two short paragraphs, front-loading purpose and then adding a clear usage note. No 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 read tool with two parameters and an existing output schema, the description covers purpose, parameters, and usage context. It could mention output pagination or limits, but overall 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 has 0% description coverage, so description compensates by explaining school_id is from list_conversations and chat_id is from its results. This adds meaningful context beyond the schema's 'integer' type and parameter names.

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 'Read a specific message conversation thread with all messages.' It specifies the verb (Read) and resource (specific conversation), and distinguishes from sibling tools like list_conversations which lists conversations.

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 includes an 'IMPORTANT' note that both school_id and chat_id are required, and explains that school_id is from list_conversations and chat_id from its results. This provides context on when to use this tool (after listing conversations) but does not explicitly state when not to use it.

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?

No annotations are provided, so the description must cover behavioral traits. It states 'Returns JSON' implying a read operation, but does not explicitly confirm safety (no destructive side effects). For a simple read tool, this is adequate but not explicit.

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 front-loaded with the main purpose in the first sentence. It is concise with two paragraphs and an Args list. Minor redundancy (first sentence and second paragraph both mention return content), but overall 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?

The description explains the tool returns school details and staff records, and references get_staff_member for more detail. Given no output schema and one parameter, it provides sufficient context for a directory listing tool, though it could mention any limits or pagination.

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 0% schema description coverage, the description must compensate. It lists 'school_id: School ID' in an Args section, providing minimal context beyond the schema. It does not give format or examples, but for a single integer parameter, the addition is functional.

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 lists school contact info and staff directory with names, roles, and phone numbers. It distinguishes from the sibling get_staff_member by noting that get_staff_member provides additional details like email and photo.

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 says when to use this tool ('List school contact info and staff directory') and when to use the alternative ('Use get_staff_member(school_id, user_id) for full staff details'). This provides clear guidance on tool selection.

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

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

With no annotations, the description carries the full burden. It states that the tool returns a paginated list and includes default page behavior, but does not explicitly confirm it is read-only or mention any side effects, rate limits, or auth requirements.

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

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

The description is concise with two sentences clearly stating the purpose and a second paragraph providing usage guidance, with no redundant or unnecessary 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?

Given that an output schema exists, the description appropriately focuses on input parameters and behavior (pagination, linking to get_post). It covers the essential aspects for a tool with two parameters and a clear output schema.

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

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

Despite 0% schema description coverage, the description adds meaning by defining school_id as 'School ID' and page as 'Page number for pagination (default: 1)', which compensates well for the missing schema descriptions.

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 that the tool gets recent posts from a school's feed with specific fields (titles, authors, dates, summaries) and distinguishes it from the sibling get_post by noting that get_post provides full details using the feed_id.

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 directs users to use get_post for full details when a feed_id is available, providing clear alternative guidance. However, it does not cover broader when-not-to-use scenarios or other siblings.

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?

No annotations provided; description only states a get operation (read) without disclosing any behavioral traits such as error conditions, authentication requirements, or side effects. Minimal disclosure for a read operation.

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?

Description is two sentences plus concise arguments list. No redundant words, front-loaded with purpose and important note, well-structured.

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 2 required parameters and an output schema, the description covers purpose and parameter sourcing. Could be improved by noting the return format (e.g., list of posts), but overall complete for basic usage.

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 0% schema description coverage, the description adds meaning by stating that school_id is the same as used in list_groups and group_id comes from list_groups results. This provides relational context beyond the schema types.

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

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

Description clearly states 'Get posts from a specific group's feed', which is a specific verb+resource. It distinguishes from siblings like get_feeds (general) and list_groups (listing groups, not posts).

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?

Description emphasizes that both school_id and group_id are required, and explicitly links school_id to list_groups and group_id to its results, providing clear context. However, it does not mention when not to use this tool or alternative tools.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It notes that image attachments are returned inline and PDF text is extracted, which is helpful. However, it omits information about authentication, error handling, rate limits, or the structure of the response beyond what 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?

The description is concise and front-loaded with purpose. The second paragraph adds behavioral detail. The 'Args:' line is somewhat redundant with the schema but still adds context. Overall, it is 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?

Given no output schema and no annotations, the description covers key return elements (body, comments, attachments with inline rendering) but lacks detail on field names, format, or error cases. It is adequate but has gaps.

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

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

The only parameter 'feed_id' is well explained: it identifies the post and references where to find it (get_feeds results). This adds significant meaning beyond the schema's bare integer type.

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 it retrieves full details of a specific post, including body text, comments, and attachments. It distinguishes itself from siblings like get_feeds (which lists feeds) by specifying the depth of detail. However, it does not explicitly differentiate from get_conversation, which could overlap.

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 no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. It only describes what the tool does, leaving the agent to infer usage context.

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

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

No annotations provided, but description mentions it returns structured data plus an inline profile photo when available. Could note it's a read-only, non-destructive operation, but the context is sufficient.

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?

Concise with summary, usage guidance, and parameter descriptions in a few sentences. No fluff.

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 get tool with two parameters and no output schema, the description covers purpose, workflow, and return value (structured data + inline photo). 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 0%, but description adds meaning: 'school_id: School ID' and 'user_id: Staff member's user ID (from get_directory results)'. This explains the source of user_id beyond 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?

Description clearly states 'Get detailed info for a specific staff member' with specific fields (email, photo, office hours). This verb+resource combination is distinct from siblings like get_directory.

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

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

Explicitly instructs to 'Use get_directory first to find the user_id, then call this for full details,' providing a clear workflow and naming the alternative tool.

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It clearly implies a read-only operation via 'Get', and an output schema exists to define the return structure. However, it does not disclose error handling (e.g., invalid student_id), authentication requirements, or any side effects. This is adequate for a simple getter but lacks depth.

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 exceptionally concise: one purpose sentence and a parameter explanation. It is front-loaded with the main purpose and contains no fluff or repetition. Every sentence adds 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?

Given the tool's simplicity (one parameter, clear purpose, output schema present), the description is nearly complete. It covers the return fields and parameter semantics. Minor omissions like error behavior or prerequisites beyond sourcing the ID are acceptable for this scope, but could be enriched with a note on failure handling.

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 description coverage is 0%, so the description must compensate. It explains that student_id is the 'id' from list_students and equates it to the roster id, adding meaning beyond the bare integer type in the schema. This is strong parameter documentation for a single parameter.

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

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

The description clearly states the action ('Get'), the resource ('admin detail for one student'), and enumerates the specific fields returned (name, grade, SIS id, linked guardians, classes). This distinguishes it from list_students (which retrieves many students) and get_student_dashboard (likely a student-facing view), even though those siblings are not explicitly named.

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

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

The description provides no explicit when-to-use or when-not-to-use guidance, nor does it name alternative tools. The only usage hint is that student_id comes from list_students, which implies a prerequisite but does not clarify the tool's niche relative to siblings like get_student_dashboard or list_students.

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?

No annotations provided, so the description must convey behavioral traits. It only describes the purpose without explicitly stating this is a read-only operation or disclosing any side effects, auth requirements, or rate 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 two concise sentences. The first sentence states the purpose and included data, and the second specifies the argument. No unnecessary words, well 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?

With only one parameter and no output schema, the description adequately explains what information is returned. However, it could be more complete by specifying the structure or fields of the dashboard response.

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 0%, but the description adds meaning to the 'student_id' parameter by explaining it is the Student ID and suggests using 'list_schools' to see available students. This goes beyond the schema's type and title.

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 it retrieves student dashboard information and lists the included data types (school, grade, classes, teachers). The verb 'Get' is appropriate, and the resource 'student dashboard' is distinct from sibling 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 description provides a hint on how to find student IDs using 'list_schools' but does not indicate when to use this tool versus alternatives or when not to use it. No guidance on usage context 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?

With no annotations, the description carries the full burden. It discloses that it requires PS_ENABLE_WRITES (write operation), emails the guardian, and supports resend. It doesn't describe error behavior or side effects in detail, but the core behavioral traits are transparent.

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: the first sentence states purpose and prerequisite, the second explains behavior, and the third provides parameter details. No filler, each 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 simple two-parameter write tool, the description covers the essential context: when to use it, where to get the ID, and the prerequisite. It does not mention the output or error cases, but the output schema exists and the rules state descriptions need not explain return values. It is 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?

Given 0% schema description coverage, the description compensates by explaining user_id as 'Guardian's user ID (from list_parents)' and implying it should be for an unregistered guardian. school_id is only restated as 'School ID', which adds minimal value, but the description meaningfully enriches user_id semantics.

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 ('Send (or resend)') and the resource ('ParentSquare registration invitation to one guardian'). It distinguishes itself from sibling tools like list_parents (listing), add_parent (adding), and bulk_invite_parents (bulk) by focusing on the single-invite scenario.

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 practical guidance: it tells the agent to get user_id from list_parents and to only invite guardians with registered=false. It also notes that the same endpoint handles resends. It doesn't explicitly contrast with bulk_invite_parents, but the context is sufficient for correct selection.

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

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

With no annotations provided, the description carries the full burden. It discloses that existing links are left untouched (non-destructive), that unlinking is destructive and not available in v1, and that write permission is required. It does not mention idempotency or behavior if the link already exists, but the provided information is substantial and context-rich.

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. The core purpose is front-loaded, followed by a crucial behavioral note and a clear argument list. No filler—every sentence earns its place, and the layout is easy to scan.

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 tool has an output schema (not shown, but indicated), so return values need not be explained. The description covers prerequisites, side effects, what it does not do, and parameter sourcing, which is sufficient for an agent to invoke this write operation correctly. The only minor gap is explicit sibling differentiation, but that's already handled in purpose clarity.

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 0%, so the description must explain parameters. It does so clearly: school_id as 'School ID', user_id as 'Guardian's user ID (from list_parents)', and student_id as 'Student ID to link (from list_students)'. This adds source guidance, making parameter meaning and acquisition straightforward.

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 ('Link') and resource ('an existing guardian to an additional student'), immediately distinguishing it from creating a new guardian (add_parent) or editing one. The phrasing 'existing' and 'additional' makes the action precise and 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?

It explicitly mentions a prerequisite (PS_ENABLE_WRITES) and clarifies that unlinking is not supported (deferred to website), which tells the agent what this tool cannot do. It also gives sources for user_id and student_id (from list_parents and list_students), which aids usage. However, it does not explicitly state 'use this instead of add_parent if guardian already exists,' relying on implication rather than a direct contrast.

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?

No annotations are provided, so the description must disclose behavior itself. It does mention that the tool returns every class in one call, and it lists the output fields (grades, teachers, room-parent counts). However, it does not explicitly state side effects (though 'list' implies read-only), error conditions, or rate limits. For a list tool this is acceptable but not exhaustive.

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 efficiently structured: a lead sentence stating purpose, a second sentence explaining usage and downstream tools, and a clear Args block. No redundant words; every sentence earns its place. The purpose 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?

The description covers the tool's purpose, parameters, and how to use the results with other tools. Since an output schema exists, return details are not needed. It lacks explicit error-handling information, but for a simple list tool with a required school_id, the description is sufficient 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 0%, but the description's Args section fully explains each parameter: school_id (from list_schools), name_contains (case-insensitive substring filter), and grade (with an example 'Kindergarten'). It adds meaning beyond the schema's bare types and demonstrates how filters behave.

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 begins with a specific verb ('List') and resource ('classes'), with detail on included fields (grades, teachers, room-parent counts). It clearly distinguishes this bulk-list operation from single-class tools like get_class, and explains what the section_id will be used for. The purpose is unambiguous and distinct from siblings.

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

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

It states 'Returns every class in one call,' which implies the use case of obtaining all classes at once. It explicitly instructs the agent to use the section_id from results with get_class, edit_class, and related tools, giving clear downstream usage. It does not name alternatives or exclusions explicitly, but the context makes when-to-use clear.

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?

No annotations are provided, so the description carries the burden. It implies a read-only operation via 'List', but does not explicitly state safety or return behavior. For a simple listing tool, the risk is low, yet important details like pagination or error conditions are absent. Adequate but not thorough.

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 filler. The purpose is front-loaded, and the parameter explanation is concise. It's appropriately sized for a simple read operation, earning a high score for efficiency and clarity.

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 tool is simple with one parameter and an output schema exists, which covers return structure. The description covers the purpose and parameter source, but does not mention any limitations or edge cases. Given the low complexity, it is reasonably complete, though it could note the distinction from list_students.

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 0%, so the description must compensate. It does by explaining the parameter: 'Class/section ID (from list_classes)', which adds meaning about its origin and type. This is helpful and reduces ambiguity, though it lacks examples or validation 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 clearly states the tool lists students enrolled in one class, with a specific verb and resource. The scope 'in one class' helps distinguish it from list_students, though it doesn't explicitly name alternatives. It's clear but could be sharper on differentiation.

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 parameter hint: 'from list_classes', which indicates where to obtain the section_id. However, it does not explicitly state when to use this tool versus list_students or other class-related tools. Some context is provided but no exclusions or alternative selection criteria.

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?

No annotations provided, so description carries full burden. Describes output but does not disclose if it's read-only, pagination behavior, or authentication requirements. Acceptable for a simple list but lacks depth.

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?

Concise with two clear paragraphs. Slightly redundant 'Args' section but not excessive. Efficient use of 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?

Covers key aspects: what it does, what it returns, how to use results. Output schema exists, so return values are handled. Adequate for the tool's complexity.

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?

Though schema coverage is 0%, the description adds significant meaning to the single parameter by explaining it as a School ID and directing to list_schools. This goes beyond the schema's type-only definition.

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

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

Clearly states it lists message conversations for a school and specifies returned data (IDs, participants, previews). Distinguishes from get_conversation by noting it provides previews only, but does not explicitly differentiate from other list 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?

Explicitly tells when to use get_conversation for full content and provides cross-reference to list_schools for finding school_id. Clear guidance on chaining tools.

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?

No annotations are provided, so the description must fully disclose behavior. It states it lists files and returns URLs, but omits any side effects, permissions, pagination, or rate limits. The operation appears read-only but is not confirmed, leaving behavioral gaps.

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, consisting of two sentences and an args list. It is efficient and front-loaded with the core purpose. However, the formatting is plain and could be improved for readability.

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 requires one parameter and has an output schema (not shown), the description should clarify the scope of 'files and documents' and any default ordering or filtering. It lacks these details, making it incomplete for an agent to use 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 0% schema description coverage, the description must compensate. It only adds 'School ID' to the parameter name, providing minimal additional meaning. It does not explain what constitutes a valid school ID or how to obtain it.

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

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

The description clearly states 'list files and documents posted for a school', specifying a verb and resource. It mentions returning file URLs for download_file, which gives some context. However, it does not differentiate from other list_* siblings like list_forms or list_schools, lacking explicit distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives. The only hint is 'returns file URLs for download_file', which implies a follow-up action but does not state when to choose this over other list or retrieval tools.

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?

No annotations provided, so description carries full burden. Describes listing behavior but does not explicitly state it is read-only or idempotent. 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?

Description is concise (3 sentences plus args), front-loaded with purpose, and no wasted words. Slightly longer due to args line but still 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?

Given an output schema exists, description adequately covers purpose, output content, and links to related tool. Lacks parameter details but schema compensates.

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 0% and description merely repeats schema with 'Args: school_id: School ID' without adding any additional meaning or context 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?

Clearly states 'List available forms and permission slips for a school' with specifics on what is shown (titles, authors, dates). Differentiates from sibling 'get_post' which provides full content.

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

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

Explicitly mentions using 'get_post' for full form content, providing an alternative. No explicit exclusions, but clear context on when to use this tool.

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?

No annotations are provided, so the description carries the full burden. It discloses the key runtime/per-school behavior ('discovered at runtime') and that it returns grade_id values for other tools. However, it does not explicitly state that the operation is read-only or mention any potential side effects or permissions, which an agent might need to know. For a simple list tool the lack is minor, but the description could be more explicit.

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 tightly written: two short sentences plus an Args bullet. It front-loads the core purpose and downstream usage, with zero fluff. The structure is easy to scan and every sentence adds 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?

With an output schema present (though not shown here), the description does not need to detail return values. It covers what the tool does, why it is used (grade_id for add_student/edit_student), the per-school runtime behavior, and the prerequisite for the parameter. An agent has everything needed to call it correctly in the intended workflow.

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 0% (the schema has no description for school_id). The description compensates by stating 'school_id: School ID (from list_schools),' which explains the parameter's meaning and origin. This is sufficient for an integer parameter, though it could add more detail about format or constraints.

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+resource: 'List a school's grades with their grade_id values.' It also specifies the intended downstream use (add_student / edit_student), which distinguishes it from the many other list_* siblings. There is no ambiguity about what this tool 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 explicitly says the grade_id is 'needed for add_student' and to 'use the returned grade_id with add_student / edit_student.' It also explains that grades are per-school and discovered at runtime, implying you must call this per school. The Args line points to list_schools as the source for the school_id, giving a clear prerequisite 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?

No annotations are provided, so the description must carry the behavioral burden. It discloses that the tool returns active post counts and descriptions, and implies a read-only list operation. However, it omits details like pagination, ordering, or potential errors, which would matter for a list endpoint. Nothing is misleading, but coverage is only 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?

The description is compact, with the core purpose stated first, followed by a useful cross-tool routing hint and a minimal parameter explanation. Every sentence adds value and there is no fluff.

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 list tool, the description plus the available output schema cover what an agent needs to call it correctly. It provides the required school_id semantics and points to related tools for the follow-up action. Minor omissions like pagination or authorization are not critical given the simplicity.

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

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

The schema provides only an integer school_id with no description, so the description's Args section adds real value: it explains the parameter's meaning and tells the agent where to find valid IDs via list_schools. This compensates well for the 0% schema 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 operation ('List groups at a school') and the expected output content ('active post counts and descriptions'). It is distinct enough from siblings like list_students or list_schools, though it does not explicitly name an alternative it is not.

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 practical usage context: it tells the agent to use list_schools to find valid school IDs and points to get_group_feed as the next step for viewing posts. It does not explicitly state when not to use this tool, but the chaining guidance is clear and actionable.

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?

Description is minimal; it states it returns link names and URLs but does not disclose whether the operation is read-only, any authentication requirements, rate limits, or side effects. Since no annotations are provided, the description carries the full burden and fails to cover these aspects.

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 and front-loaded with the purpose, followed by args. No extraneous information. However, it could be slightly more structured (e.g., using bullet points or clearer separation of args).

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 tool has only one parameter and an output schema, so completeness requirements are moderate. The description adequately states the purpose and return values, but lacks usage context and behavioral details. Given no annotations, it meets the minimum but is not thorough.

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 0% (no description in schema). The description adds only 'school_id: School ID', which is trivial and does not explain the parameter's format, how to obtain it, or any constraints (e.g., required format). This adds minimal 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?

Description clearly states it lists quick-access links for a school, provides examples (calendars, menus, forms), and mentions return values (names and URLs). This differentiates it from sibling tools like list_files or list_forms, achieving a specific verb+resource distinction.

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

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

No explicit guidance on when to use this tool versus alternatives. The description does not mention conditions for use, prerequisites, or scenarios where another tool might be preferable.

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?

No annotations provided, and the description only says 'list', which implies read-only behavior. It lacks details on pagination, ordering, permissions, or any side effects.

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 but includes a redundant 'Args' section that repeats the schema. Every sentence earns its place, but structure could be tighter.

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?

Output schema exists, so return values are covered, but missing behavioral details like whether it lists all notices or has filters, and what authorization is needed. Given sibling tools, more context would improve completeness.

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 0%, and the description only repeats the parameter name 'school_id' without explaining its meaning or how to obtain it. For a single required parameter, more context is needed.

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

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

The description clearly states the tool lists alerts and notices for a school, with examples (urgent alerts, secure documents, consent forms), and differentiates from sibling tools like list_conversations and list_files.

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

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

No guidance on when to use this tool vs alternatives like list_forms or list_polls. The description only implies use for school notices but does not specify context 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?

With no annotations provided, the description carries the behavioral disclosure burden. It mentions returning the full roster in one call (no pagination) and specifies filters as case-insensitive, which are useful behavioral details. It doesn't explicitly state read-only semantics, but the operation is inherently a read and no side effects are suggested. This is adequate for a list operation.

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 and well-organized: a single-line purpose, a brief usage note, and a clear Args section. Every sentence adds value, and the most important information (what it does and how to use results) 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 that an output schema exists to define return values, the description covers everything needed for correct invocation: purpose, source of school_id, filters, and downstream usage. It explicitly states the full roster is returned in one call, closing any pagination question. 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?

Schema description coverage is 0%, but the description fully explains each parameter: school_id origin, name_contains as a case-insensitive substring filter, and student_name_contains similarly. This adds meaning far beyond the schema's bare type definitions, making parameter interpretation unambiguous.

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 lists guardians/parents on a school's admin roster and enumerates the fields returned (user_id, name, email, phone, linked students). This verb-resource pairing distinguishes it from sibling tools like list_students or add_parent, leaving no ambiguity about its function.

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

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

It explicitly instructs to use the returned user_id in edit_parent and link_guardian_to_student, and references school_id from list_schools, providing integration context. However, it does not state when to avoid this tool or mention alternatives, though no sibling provides a conflicting listing capability, so this is a minor gap.

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?

No annotations provided, so description must convey behavioral traits. It implies read-only but does not explicitly state safety, authorization needs, or side effects. Lacks clarity on permissions or rate 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?

Description is concise: two sentences plus args. Front-loaded with main purpose. No unnecessary words. Efficient but could be slightly more structured with bullet points.

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 an output schema (not shown), description adequately hints at return values. Parameter info is minimal but complete for a single parameter. However, no coverage of edge cases or usage context beyond basic description.

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

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

With 0% schema coverage, the description adds minimal value beyond the schema title. The args list essentially repeats the schema's 'School Id' without additional context like format, source, or constraints.

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 clearly states it lists payment items for a school, and elaborates on what is shown: summary stats (upcoming/paid counts, total amount) and each payment post with items and prices. This distinguishes it from sibling tools like list_files or list_schools.

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

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

No explicit guidance on when to use this tool versus alternatives. The description only explains functionality without mentioning exclusions or prerequisites.

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?

No annotations are provided, so the description carries the full burden. It reveals the return type (photo URLs) and mentions pagination via the page parameter, but it does not disclose other important behaviors such as authentication requirements, rate limits, or error handling for invalid school_id. The description adds minimal behavioral context beyond what is inferred.

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 very concise: two sentences followed by a simple list. It is front-loaded with the core purpose and the key relationship to download_file. No unnecessary words or repetition.

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 simplicity and the existence of an output schema, the description covers the basics. However, it omits details like the maximum page size, ordering, or how to handle the case of no photos. The reference to download_file is helpful, but for a tool with 0% schema coverage and no annotations, more completeness is 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 description coverage is 0%, so the description must compensate. The Args section provides basic explanations: 'school_id: School ID' and 'page: Page number (default: 1)'. These are nearly tautological and add little meaning beyond the parameter names. The description fails to explain the role of page in pagination or any constraints.

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 'list' and resource 'photos for a school', and mentions 'Returns photo URLs that can be used with download_file', making the purpose specific. However, it does not explicitly distinguish it from sibling list tools like list_files.

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 the tool is for retrieving photo URLs for downloading, but it does not provide when-not-to-use guidance or contrast with alternatives like list_files. It gives a basic use case but lacks 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?

No annotations are provided, so the description must disclose behavior. It mentions output contents (questions, options, vote counts, winning option) but does not detail read-only nature, authentication needs, or pagination. Some gaps remain.

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, with purpose front-loaded, and every sentence adds value. It is efficient without being overly terse.

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 an output schema, the description adequately covers what the tool returns. It mentions key output fields and the single required parameter, though it could note if all polls are returned.

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

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

The description only repeats the parameter name and type from the schema without adding meaning. With 0% schema description coverage, it fails to compensate for missing documentation.

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 'list' and resource 'polls for a school', and specifies the output includes questions, options, and vote counts. It distinguishes from other list tools by focusing on polls.

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 indicates when to use (to list polls for a school) but does not provide when-not-to-use or suggest alternatives. It is clear but lacks explicit exclusion or sibling differentiation.

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?

Describes that it parses sidebar navigation and returns a list of sections, implying read-only. No annotations exist, but description discloses the mechanism. Lacks mention of error handling or edge cases, but overall transparent.

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?

Concise: two short paragraphs with a clear summary and an Args section. No redundant or filler 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 simple tool with one parameter and an output schema, the description explains return type and examples. Could mention behavior on invalid IDs, but output schema likely covers that.

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?

Single parameter 'school_id' is explained with instruction to use list_schools to find IDs, adding significant value beyond the schema's integer type. Schema coverage is 0%, so description fully compensates.

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 lists features for a school by parsing sidebar navigation, and gives examples of returned sections. It distinguishes from sibling 'list_schools' which lists schools, not features.

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

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

Provides guidance on when to use (to see available features per school) and references list_schools to obtain school_id. Does not explicitly state when not to use, but alternatives are clear from sibling tools.

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?

Description implies read-only operation via 'List' and mentions return format. No annotations provided, but description adds value by specifying output structure and usage hints. Could explicitly state non-destructive 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?

Three concise sentences front-loading purpose, then adding utility and alternative guidance. No unnecessary 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?

Complete for a simple list tool with no parameters and an output schema: describes purpose, output, usage of results, and alternative tool for other needs.

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?

No parameters, so description needs no param info. Baseline for 0-param tool is 4. No additional context needed beyond schema, which already covers all.

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?

Clear verb 'List' with specific resources 'schools and students'. Distinguishes from sibling get_directory by stating its purpose is for contact info, not listing.

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

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

Explicitly states to use output school_id and student_id in other tools, and directs to get_directory for contact info, providing clear when-to-use and when-not-to-use guidance.

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

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

No annotations are provided, so the description must disclose behavioral traits. It implies a read-only list operation and describes the output structure, but lacks details on error handling, rate limits, pagination behavior (e.g., order, total count), or authentication requirements. The disclosure is adequate but not comprehensive.

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 plus an argument list—and front-loaded with the main purpose. Every sentence adds value: purpose, output summary, cross-reference to get_post, and parameter definitions. It could be more structured (e.g., bullet points) but is 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?

The tool has only 2 parameters and an output schema (not shown), so the description covers the basic functionality and output fields (title, progress, author). However, it misses details like the feed_id (referenced in the cross-reference), sorting, filtering, or error behavior. It is adequate for a simple list tool but lacks completeness for an agent to fully understand all aspects.

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 0%, so the description must explain parameters. It provides short explanations for school_id ('School ID') and page ('Page number for pagination (default: 1)'), which adds value beyond the bare schema. However, it lacks specifics like valid value ranges, format, or examples, so it is only moderately helpful.

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 starts with a specific verb 'List' and clearly identifies the resource: 'sign-up and RSVP posts for a school', with examples of types (item donations, volunteer slots, event RSVPs). It distinguishes from sibling tool get_post by advising to use that for full details, making the purpose distinct.

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 guidance on what the tool returns (title, progress, author) and explicitly mentions an alternative: 'Use get_post with the feed_id to see full signup details'. However, it does not explain when not to use this tool versus other siblings like list_feeds, but the advice is sufficient for basic differentiation.

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?

No annotations are provided, so the description carries the full burden of disclosing behavior. It correctly implies the operation is read-only (via 'List'), states the fields returned, and explains the filter. However, it does not mention potential pagination, result limits, or error conditions, which would be helpful for a list tool but are not critical.

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. It front-loads the core purpose and output fields, then gives a single line of usage context, followed by clean parameter explanations. No redundant or unnecessary sentences; 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?

The description covers the essential usage context: purpose, parameters, and a downstream use case. Since an output schema exists (per context signals), the description need not explain return values in detail, though it already does. It does not address pagination or auth, but these are typically handled by the schema or platform conventions and are not critical for a simple list tool.

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

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

Schema description coverage is 0%, so the description fully compensates. It explicitly explains both parameters: school_id is sourced from list_schools and name_contains is a case-insensitive substring filter. This adds significant meaning beyond the bare type definitions in 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 states a specific verb ('List') and resource ('a school's staff and admins'), and it enumerates the returned fields. This distinguishes it clearly from siblings like list_students, list_parents, and get_staff_member. The first sentence alone makes the tool's purpose 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 provides concrete usage guidance: it tells the agent that the returned user_id should be used with add_class_staff, and it specifies the source of school_id (from list_schools). However, it does not explicitly state when not to use this tool or contrast it with get_staff_member, though the 'list' vs. 'get' distinction is implied by the example.

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

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

With no annotations, the description carries full burden. It discloses that it returns the full roster in one call, implies read-only behavior, and lists the output fields. It also tells the agent how to leverage the returned id, which is useful behavioral context not captured in the schema.

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

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

The description is concise and front-loaded: it states the purpose first, then the output fields, then the usage note, then the parameter list. Every sentence earns its place with no redundant fluff.

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 list tool with three parameters and a clear output specification, the description is largely complete. It covers the return format and how to use the output. It doesn't mention pagination, ordering, or volume limits, but these are not critical for this tool's expected use.

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 0%, so the description must fully explain parameters. It does so: school_id is sourced from list_schools, grade is a case-insensitive filter with an example, and name_contains is a case-insensitive substring filter. This adds meaning beyond the bare schema types.

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

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

The description clearly states the tool lists students on a school's admin roster and specifies the returned fields (id, name, grade, SIS id, guardians). This distinguishes it from class-specific listing tools like list_class_students, even though it doesn't name them.

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

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

It gives context on how to use the result IDs (as student_id in related tools) and explains the optional filters, but it does not explicitly state when to use this tool over alternatives like list_class_students or list_grades. No exclusions or alternative routes are mentioned.

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?

No annotations are provided, so the description must carry the full burden. It only states the action is to list entries, implying a read operation, but does not disclose authentication needs, pagination, error handling, or idempotency. Minimal behavioral insight.

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 relatively concise (3 sentences plus an Args block). The main purpose is front-loaded. However, the Args block largely duplicates the schema, and could be omitted or integrated more 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 list tool with one parameter and no output schema shown, the description gives a reasonable overview of the returned fields (month, activity type, notes, hours). However, it lacks details on pagination, ordering, date ranges, and empty results. Adequate but incomplete.

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 0% schema description coverage, the description should compensate. It only names the parameter 'school_id' and calls it 'School ID', which adds no semantics beyond the schema's title and type. No format, constraints, or derivation hints.

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), resource (volunteer hours), and scope (for a school, entries with month, activity type, notes, hours). It distinguishes itself from sibling tools which are generally about files, calendars, conversations, etc., so no 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?

No guidance on when to use this tool versus alternatives. For example, it does not differentiate from potentially related tools like list_signups. No context on prerequisites or conditions.

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?

No annotations are provided, so the description carries the full burden. It discloses the auth requirement (PS_ENABLE_WRITES), the atomicity (global lock, single request), the preservation of other classes, and the optionality of from_section_id. This is comprehensive behavioral disclosure covering safety and side effects.

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 longer than ideal but well-organized: purpose first, then safety, behavior, and args. Each section adds necessary detail, and the critical safety warning is prominent. Slight redundancy in the 'full class list replaced' vs 'other classes preserved' phrasing, but overall 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 write operation with parallelism hazard, the description covers prerequisites, concurrency constraints, behavioral nuances, and parameter sources. An output schema exists, so return format is handled separately. Nothing essential 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?

Schema coverage is 0%, so the description must compensate. It includes an 'Args:' section that explains each parameter with purpose and provenance (e.g., 'from list_students', 'from list_classes'), and clarifies the optionality of from_section_id with behavioral consequences. This fully compensates for the lacking schema descriptions.

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

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

States a specific verb and resource: 'Switch a student from one class to another.' It also distinguishes itself from sibling tools by explaining it does both halves of the switch in a single request and can add a class while preserving others. This makes the tool's unique role clear.

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

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

Provides explicit guidance about when NOT to use it: 'Never call this tool or another class-staff/student-enrollment write in parallel.' It also explains the effect of omitting from_section_id, guiding how to use it for adding rather than moving. However, it does not explicitly contrast with add_class_students or remove_class_students, leaving some ambiguity about when to prefer this over those alternatives.

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

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

With no annotations provided, the description carries the full burden, and it delivers. It discloses that this is a write operation requiring PS_ENABLE_WRITES, explains the concurrency risk and the serialization behavior, details exactly what happens when removing by user_ids vs role, and explicitly states that 'Everyone else on the class is preserved.' It also recommends verifying with a fresh get_class read, making side effects transparent.

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?

Though lengthy, every sentence earns its place. The structure front-loads the core action, then a critical SAFETY warning, then usage semantics, then parameter details. There is no filler or repeated information. The layout is clean and scannable, with the warning prominently placed to prevent misuse.

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 mutation tool with no annotations and high behavioural risk, the description is remarkably complete. It covers prerequisites, safety constraints, operational steps, parameter semantics, and even mentions verifying results. The output schema existence means return values need not be explained, and nothing an agent needs to call this correctly 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 description coverage is 0%, so the description must compensate, and it does thoroughly. It explains section_id as the class/section ID from list_classes, clarifies that user_ids is optional if role is given, and enumerates the role values (TEACHER, ASSISTANT, ROOM_PARENT) with an example. This adds meaning far beyond the bare JSON 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 verb ('Remove') and a clear resource ('staff or room parents from a class'), immediately distinguishing it from siblings like add_class_staff. It also specifies the class context and the two removal modes, so an agent can tell what the tool does 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 provides explicit usage guidance: it warns against parallel calls with add_class_staff, explains when to use user_ids versus role, clarifies that role removes all holders of that role, and even gives a strategy for school-wide clearing via list_classes. This goes far beyond basic 'when to use' and includes concrete operational directives.

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

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

With no annotations provided, the description carries full responsibility. It discloses the write requirement, the serialization safety behavior, the preservation of other classes, and the rule that it won't empty a class. This is far beyond the minimal and gives the agent a complete picture of side effects and constraints.

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

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

The description is longer than average but well-organized with a SAFETY section and explicit parameter explanations. Every sentence adds value—requirements, serialization warning, preservation rule, and parameter sources. It is front-loaded with the core action and constraints, though it could be slightly tightened without losing information.

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

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

For a write operation with three required parameters, the description covers the action, prerequisites, safety notes, parameter semantics, and behavioral guarantees. Since an output schema exists, return format is not needed. Nothing crucial is missing for an agent to invoke this tool correctly.

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

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

Schema coverage is 0%, so the description must explain each parameter. It does: school_id is the school the class belongs to; section_id comes from list_classes; student_ids come from list_class_students. This adds meaning beyond the bare property names and even provides sourcing guidance, fully compensating for the lack of schema descriptions.

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 'Remove specific students from a class' and adds a key constraint: 'student_ids is required: this tool will not empty a class.' This distinguishes it from a general removal tool and clarifies its scope. Though it doesn't name a sibling, it is unambiguous 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?

It provides context on when to use: it requires PS_ENABLE_WRITES, warns against parallel writes, and specifies that each student's other classes are preserved. It does not explicitly list alternatives like move_student_to_class or add_class_students, but the wording implies this is for pure removal, not moving. This is clear context without explicit exclusions, so a 4.

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?

Since there are no annotations, the description carries the full burden. It discloses the PS_ENABLE_WRITES prerequisite, explains that hidden classes are invisible to all user roles, and notes that the change takes effect on a date (defaulting to today). This covers key behaviors. It doesn't mention what happens to existing posts or whether the action is reversible, but for a visibility toggle the given details are substantial.

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: it leads with the purpose and requirement, then the critical usage context, then a neatly formatted Args list. Every sentence contributes something meaningful—no fluff or redundancy.

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

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

With an output schema present, return values are covered elsewhere. The description covers the purpose, workflow, prerequisites, parameter semantics, and effects. It does not address error handling or invalid ID scenarios, but these are typically less critical for a toggle operation and are partially inferable from the schema. Overall it's quite 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 0%, so the description must explain all parameters, and it does so thoroughly: each arg is given a clear meaning, including that section_ids come from list_classes, the boolean semantics of visible, and the date format plus default behavior. This adds significant value beyond the bare schema titles.

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 (show/hide), the resource (classes), and the audience (staff, parents, students). It is unambiguously distinct from read-only siblings like list_classes and from creation tools like add_class by mentioning the write permission requirement and the hidden-by-default behavior.

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

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

Provides specific context: newly created classes start hidden, so add_class needs this before anyone can see or post. This implies when to use it (right after creation) and gives the workflow. However, it does not explicitly name alternative tools (e.g., edit_class) or state when not to use it, so it's clear but 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?

No annotations are provided, so the description carries full burden. It states that submitting the code completes login but does not disclose potential behaviors such as code expiration, failure modes, or side effects (e.g., rate limiting, token creation). This leaves uncertainty for the agent.

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 brief, with two short paragraphs and an Args section. It front-loads the main purpose and provides necessary detail without 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?

The description adequately covers the tool's purpose and parameter, but given the presence of an output schema and no annotations, it omits details on return values or error handling, which are important for a complete understanding of tool behavior.

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 0%, but the description compensates by specifying that 'code' is a '6-digit verification code from your email', adding concrete constraints and source beyond the basic string type in 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 'submit' and the resource '6-digit MFA verification code', specifying its role in completing ParentSquare login. None of the sibling tools handle MFA, so it is well-distinguished.

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 the tool (when an MFA error is returned and a code is sent to email) and instructs the user to check email. It does not explicitly list alternatives or exclusions, but the context is clear for an auth-specific tool.

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