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

With no annotations, the description carries the behavioral burden. It discloses the requirement for PS_ENABLE_WRITES and the critical side effect that new classes are hidden until set_class_visibility is called. It also implies that staff are not automatically assigned. These are meaningful behaviors beyond the simple 'create' action.

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 tight and well-ordered: a one-sentence purpose, a brief paragraph on hidden behavior and next steps, then a clean Args list. No filler or redundancy; the most important behavioral note is front-loaded.

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

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

For a simple create operation with 3 params and an output schema present, the description covers everything an agent needs: purpose, required permission, parameter semantics, and the hidden-class behavior. It even points to list_grades for valid IDs and suggests follow-up tools. No critical gaps remain.

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's Args section is the sole documentation. It explains each parameter: school_id as School ID, name with an example, and grade_ids with a source (list_grades). This fully compensates for the schema's lack of 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 states a clear verb and resource: 'Create a new class (section) at a school.' It distinguishes itself from siblings like edit_class and set_class_visibility by explicitly noting that new classes are hidden until set_class_visibility is called, and that teacher assignment is done via add_class_staff. This makes the tool's role 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 clear workflow context: after creating a class, you must call set_class_visibility to make it visible and add_class_staff to assign teachers. This implicitly tells the agent when to use this tool (for creation) versus those others. It doesn't explicitly say 'do not use this for editing' but the workflow guidance is strong.

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, and it does so thoroughly. It discloses the concurrency hazard, the fact that the server replaces the full staff list internally, the preservation of existing staff, deduplication of current roles, and role-transfer behavior for people on a different role. It also includes the required environment flag and the instruction to serialize with read verification.

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 appropriately structured: a one-sentence purpose, a critical safety note, detailed concurrency guidance, and a clean Args breakdown. Every sentence conveys non-redundant information, and the matching risk is placed prominently before more detailed parameter documentation.

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 presence of an output schema and the tool's complexity, the description covers everything required to invoke it correctly: required permission flag, concurrency constraints, where to get IDs, role values, and behavior for existing associations. The return format is not described, but the presence of an output schema satisfies that requirement.

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 almost perfectly does. It maps section_id to list_classes, user_ids to list_staff or list_parents (depending on role), explicitly enumerates the accepted role values, and clarifies that class_title is an optional label defaulting to the role name. This adds valuable source and value semantics beyond the bare 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 a specific verb-resource pairing: 'Assign teachers, assistants, or room parents to a class,' which clearly states what the tool does and the types of roles it handles. The explicit mention of preserving existing staff and contrasting with remove_class_staff differentiates it from sibling tools without requiring schema inspection.

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 strong when-to-use context: it is for adding staff roles, requires PS_ENABLE_WRITES, and should never be called concurrently with remove_class_staff. It even instructs verifying with a fresh get_class read before the next class-staff write. It does not explicitly say 'for removing staff use remove_class_staff,' but that is strongly implied by the add/preserve semantics.

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 behavioral burden. It discloses the required permission (PS_ENABLE_WRITES), the serialized nature of writes and the need to avoid parallelism, idempotency (re-running safe, skipping existing students), and that it does not disturb existing class memberships. This is exceptionally 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 longer than a single sentence but well-structured: purpose/requirement, SAFETY callout, behavior notes, and usage example, then an Args section. Every sentence carries meaning, and key information is front-loaded. Slightly verbose but not redundant.

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

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

The description covers permissions, safety, idempotency, example usage, and parameter details. It does not describe the return value, but an output schema exists (context says has output schema: true), so that gap is acceptable. For a write tool with no annotations, 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 has 0% description coverage, so the description fully compensates. It explains each parameter's meaning and origin: section_id from list_classes, student_ids from list_students. This adds critical context (that these are IDs from other tools) that the schema's bare 'integer' and 'array' types do not provide.

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 action ('Enroll students in a class') and clearly differentiates it from sibling tools like remove_class_students and move_student_to_class. The description further clarifies it adds everyone in a single call without disturbing existing enrollments, making the scope 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 explicit guidance: gives a concrete use case ('assign a whole grade at the start of the year') with a workflow referencing list_students(grade=...), and warns against parallel calls, recommending a fresh read after. This is clear when-to-use and how-to-use guidance, and it distinguishes from alternatives implicitly.

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 a required permission (PS_ENABLE_WRITES), the invariant that a parent is always attached to at least one student, and the notable behavior that the new user id is not returned. These are important and beyond what the schema conveys.

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 short introductory paragraph followed by an Args block. The key points (requirement and no return id) are front-loaded, and the parameter list is easy to scan. No wasted sentences.

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 create tool with 6 parameters and an output schema, the description covers the essential prerequisites, the attachment requirement, and the crucial fact that the new id is not returned. It omits error behavior and field formats, but these are not critical for basic invocation. Given the output schema exists, it doesn't need to explain return values beyond the id note.

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 add meaning. It provides a brief line for each parameter (e.g., 'student_id: Student ID to attach the guardian to (from list_students)') which adds context beyond titles, but the descriptions are minimal and don't explain formats, constraints, or relationships beyond the basic mapping.

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 clear verb ('Create') and resource ('guardian/parent') and specifies the linking to a student. It is unambiguous about what the tool does. However, it does not explicitly differentiate from sibling tools like link_guardian_to_student, so it falls short of a 5.

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

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

The description implies when to use it (to create a new parent) but does not mention alternatives or explicitly state when not to use it. It gives a prerequisite (PS_ENABLE_WRITES) but lacks clear routing among the many parent-related 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 behavioral burden and succeeds: it discloses that ParentSquare emails a registration invite, that section_ids create direct assignments because ParentSquare's own 'invited classes' field delays assignment until registration, and that is_admin grants Admin rather than Staff access.

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 structure is effective: a one-sentence purpose, a compact behavioral note about the registration invite and section assignment, and a skimmable Args list. It is slightly wordy in the ParentSquare explanation, but that detail justifies 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 10-parameter mutation tool with no annotations and an output schema, the description is complete: it covers required permissions, side effects, parameter semantics, and the non-obvious class-assignment behavior. Return values are appropriately left to the 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?

Schema description coverage is 0%, but the description compensates fully by explaining every parameter, including optionality, defaults, and provenance. Examples include email being 'optional but needed for them to register,' section_ids coming 'from list_classes,' and class_role being 'TEACHER (default) or ASSISTANT.'

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 verb and resource: 'Add a teacher or other staff member to a school.' This clearly distinguishes the operation from sibling tools like add_student and add_parent, and the mention of class_role and is_admin further sharpens the 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 provides clear context for when to use the tool—adding staff and optionally assigning them to classes immediately—and states the prerequisite PS_ENABLE_WRITES. It does not explicitly name alternatives such as add_class_staff or edit_staff, so exclusion guidance 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 burden and excels: it discloses that the created id is not returned, that the roster is read back to verify success, and that a 5xx error may still mean the student was created because the error page renders after saving. It also flags that there is no delete route for duplicates, which is critical non-obvious behavior.

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 dense but every sentence earns its place: the purpose is front-loaded, the workflow advice is actionable, and the 5xx caveat is essential. There is no filler or vague boilerplate.

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

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

For a tool with no annotations and low schema coverage, the description covers everything needed: precondition (PS_ENABLE_WRITES), prerequisite lookup (list_grades), post-write retrieval (list_students), failure semantics, parameter meaning, and duplicate-deletion risk. An output schema exists, so detailed return-value documentation is not necessary.

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. Each parameter gets a one-line meaning, including the crucial note that grade_id comes from list_grades and that student_sis_id is optional and external. It could add more constraints (e.g., uniqueness expectations), but the provided semantics go well 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 opens with a specific verb and resource: 'Create a new student on a school's roster.' This clearly distinguishes it from sibling tools like add_parent, add_staff, and edit_student, and the focus on roster creation is immediately 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 requires PS_ENABLE_WRITES, tells the agent to use list_grades(school_id) to obtain grade_id, and instructs to call list_students afterward because the new id is not returned. It does not explicitly state when-not-to-use this tool versus edit_student, but the creation-vs-edit distinction is strongly implied.

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

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

The description discloses that the tool requires PS_ENABLE_WRITES (a prerequisite) and that it automatically skips already registered guardians, which is a behavioral nuance not apparent from the schema or annotations. It also indicates that the response reports how many were notified, which adds transparency about output. This is valuable beyond 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 well-structured, with a clear purpose statement, behavioral notes, and a concise parameter section. It is front-loaded with the most important context (what it does and the requirement), followed by workflow details. No superfluous wording.

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

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

Given the tool's moderate complexity (two params, clear purpose) and the presence of an output schema (not provided in detail but indicated), the description covers the essential aspects: purpose, prerequisites, parameter semantics, and behavior. It does not explain the output format in detail, but the output schema is available, and the description mentions the response reports notified count. This is complete enough for an agent to use it correctly.

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

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

The schema provides only names and types (school_id: integer, user_ids: array of integers), with 0% schema description coverage. The description adds critical meaning by explaining that user_ids come from list_parents and should be unregistered guardians. It also implicitly defines school_id as the identifier for the school. This compensates for the lack of schema descriptions, though it could be more explicit about the exact 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 action (send registration invitations), the target (multiple guardians), and the purpose (to register them). It distinguishes itself from the sibling tool 'invite_parent' by focusing on bulk invites, and it refers to related tools like 'list_parents' for context.

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

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

The description explicitly states when to use this tool ('to invite all' unregistered guardians) and provides a clear workflow: get user_ids from list_parents(school_id), typically those with registered=false. It does not explicitly mention when not to use it, but the workflow is specific enough to guide 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 carries full behavioral burden. It states that it downloads and saves to local disk and returns the path, which is the core behavior. However, it does not disclose details like overwrite behavior, error handling, network requirements, or any side effects beyond writing a file. A simple but thin behavioral description.

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: purpose statement, return value, source guidance, then an args list. Every sentence contributes information without redundancy or fluff. Front-loaded with the verb phrase and key behavior.

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 only 2 parameters, simple behavior, and an output schema (which likely details the returned path), the description covers the essentials: what it does, where inputs come from, and output. It does not elaborate on potential edge cases, but that is acceptable for this simplicity and the presence of an 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?

Schema description coverage is 0%, so the description fully compensates. It explains the 'url' parameter as the file URL from specific sources, and 'filename' as an optional custom filename with default behavior (uses original from URL). This adds meaningful semantic detail beyond the bare 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 'Download' and the resource 'a photo, video, or file to local disk from a ParentSquare URL'. It also specifies the return value (local file path). This differentiates it from all sibling tools, which are list/get operations without local disk writes.

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 instructs to use URLs from list_photos, list_files, or get_post attachment results, which gives clear context on when to use the tool. It also explains the optional filename default behavior. While it doesn't mention when not to use it, there are no alternative download tools among siblings, so no exclusion needed.

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

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

With no annotations, the description carries the full behavioral burden, and it delivers: it discloses the read-modify-write mechanism, states that only supplied fields are changed, and warns that grade_ids replaces the current grades. This gives the agent accurate expectations about 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?

Each line carries distinct information: purpose, permission, behavioral mechanism, staff exclusion, then a clean Args block. There is no filler, and the most decision-relevant details are front-loaded.

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

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

For a 5-parameter write tool with zero annotation coverage, the description covers prerequisites, update semantics, parameter semantics, and the alternative for staff. The presence of an output schema means the lack of return-value documentation is not a gap.

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

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

Schema description coverage is 0%, so the description must explain every parameter, and it does: section_id is sourced from list_classes, name/room are marked optional with a format example, and grade_ids is explicitly 'new list ... replaces the current grades.' This adds substantial meaning beyond the bare types and null defaults.

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 states a precise action and resource: 'Rename a class or change its room code / grades.' It enumerates exactly which attributes are editable, so an agent can immediately distinguish edit_class from sibling mutators like set_class_visibility or add_class_staff.

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 an explicit precondition ('Requires PS_ENABLE_WRITES') and a when-not-to-use rule: 'Staff are not affected; use add_class_staff / remove_class_staff for those.' This is a clear decision rule that prevents the most likely misuse, without making the agent infer from the sibling list.

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 behavioral disclosure burden. It provides strong context: the permission requirement, partial-update semantics ('Only provided fields change'), and a safety-relevant effect ('existing student links are preserved'). This goes well beyond the raw 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 compact and well-structured: an opening purpose line, two behavioral notes, and a clean Args list. Every sentence adds useful information with no filler or repetition of schema details.

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 targeted guardian-edit tool, the description covers the required permission, how to obtain the required user_id, the partial-update behavior, and all parameters. An output schema exists, so not describing return values is acceptable. Nothing critical 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 Args block is essential. The description explains all six parameters, clarifies which are optional, and adds critical usage guidance for user_id ('from list_parents') that the schema alone does not provide.

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 clear, specific verb and resource: 'Update a guardian's name, email, or phone.' This directly states what the tool does and distinguishes it from sibling tools like add_parent, invite_parent, or link_guardian_to_student.

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

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

The description gives useful context by noting the PS_ENABLE_WRITES requirement and instructing the agent to obtain user_id from list_parents(school_id). It does not explicitly state when not to use this tool in favor of an alternative, but the intended editing use case is 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 present, so the description carries the full burden. It discloses the PS_ENABLE_WRITES requirement, states that only provided fields change, explicitly says class assignments and STAFF/ADMIN access level are left untouched, and notes that guardians are rejected. This makes side-effect behavior clear for a mutating 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 front-loaded with a one-sentence purpose, followed by a compact behavioral note and a clean Args block. There is no filler; every sentence provides actionable guidance.

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 mutating tool with two required identifiers and six optional update fields, the description covers prerequisites, side-effect boundaries, alternative routing, and all parameter meanings. An output schema exists, so return-value documentation is unnecessary; nothing essential 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 manual Args list is essential. It annotates school_id and user_id as identifiers, clarifies staff_id as the school's own external ID, gives an example for title, and marks every optional attribute, adding semantics the schema lacks.

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

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

The first sentence names the exact operation ('Update a staff member's') and enumerates affected fields (name, email, phone, title, staff ID). It also separates itself from sibling tools by naming add_class_staff/remove_class_staff and edit_parent for related actions, making its 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?

It explicitly says to use add_class_staff/remove_class_staff for class changes and edit_parent for guardians, and tells the agent to obtain user_id from list_staff(school_id). This gives clear when-to-use and alternatives guidance with no ambiguity.

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 burden. It does so well: it states this is a partial update, that omitted fields are preserved, and that class enrollment is untouched. It doesn't state whether the operation is reversible, but it covers the key side effects 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?

Front-loaded with the core action and key constraint (provided fields only), then adds auth requirement, side-effect boundary, and parameter guidance. 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?

Covers purpose, partial-update semantics, required permission, and explicit exclusion of class enrollment. It does not describe the return value, but an output schema exists and the write action is straightforward.

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 zero parameter descriptionscars, but the Description adds meaning: it identifies which params are new values (first_name, last_name, student_sis_id, grade_id), marks grade_id as sourced from list_grades, and clarifies that optional fields are only updated when provided. This compensates well for the schema's lack of 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 first sentence states a specific action ('Update') on a specific resource ('an existing student') plus the settable fields (name, SIS ID, grade level). It is unmistakably distinct from add_student, edit_class, and read-only list/get 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?

The description explicitly declares the write prerequisite (PS_ENABLE_WRITES), clarifies that only provided fields change, and explicitly routes class-enrollment changes to sibling tools (add_class_students, remove_class_students, move_student_to_class). An agent knows when to call this tool and when not to.

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 covers it well: it reveals the ICS export source, the exact JSON array shape with event fields, and the empty-result scenario. It even explains why results may be empty and how to recover, going well beyond 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 main purpose is front-loaded in one sentence, followed by a valuable fallback note and a minimal args line. Every sentence earns its place; no filler or repeated schema noise.

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 a single integer argument, no output schema, and no annotations, the description is unusually complete: it documents the return payload, covers the foreseeable no-events case, and names the two alternate tools to pursue. Nothing needed to invoke the tool 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?

The only parameter is school_id, and the description's 'Args: school_id: School ID' merely restates the schema's property title and type. With schema_description_coverage at 0%, the description should compensate, but it adds no guidance about where to obtain the ID, format constraints, or validation.

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 opens with 'Get calendar events for a school using the ICS calendar export', naming a specific verb, resource, and data source. It also distinguishes itself from feed/post tools by explaining when calendar data appears as images/PDFs instead.

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 routing: if get_calendar_events returns no events, use get_feeds to look for posts with 'calendar' in the title or image/PDF attachments, then get_post to view them. This is exactly the when-to-use and alternative selection guidance an agent needs.

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 explains the return content (user_id and assoc_id) and notes it's for viewing current state, but lacks details on authentication, rate limits, or any side effects (unlikely for a get). It adds moderate value beyond a bare fetch.

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 a clear intro, a usage note, and a parameter definition. It's front-loaded and to the point, though the usage note could be integrated more smoothly.

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 one parameter and an output schema, the description covers purpose, parameter, and use case adequately. It doesn't need to explain return values since output schema exists. Missing only minor behavioral details like pagination or error scenarios, which are irrelevant here.

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 single parameter section_id is explained as a class/section ID and imported from list_classes, compensating for the 0% schema coverage. This gives the agent clear sourcing guidance and prevents misuse.

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 fetches one class and its full staff list, specifying the resource and content. It distinguishes from siblings like list_classes (list all) and list_staff (global staff), making the purpose unmistakable.

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 advises using this tool before changing staff to see the current state, providing a concrete use case. It implies the section_id comes from list_classes, but doesn't explicitly list exclusions or alternatives. Still, the 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?

No annotations are provided, so the description carries the burden. It discloses that the tool reads a conversation thread with all messages, which implies a read-only operation. However, it doesn't describe return format, pagination, or any side effects. The description is accurate and adds some behavioral context (returns all messages in the thread), 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 concise and front-loaded with the core purpose. The IMPORTANT note and Args section are clearly structured. It could be slightly more compact, but every sentence earns its place by clarifying required parameters and their provenance.

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 (so return values are documented elsewhere), the description covers the essential context: what it reads, that both parameters are required, and where to get the parameter values. It doesn't mention error conditions or edge cases, but for a simple read operation with an output schema, this is adequate.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains that school_id is the same one used in list_conversations and chat_id comes from list_conversations results. This adds meaning beyond the bare schema types (integer) and clarifies the relationship between parameters and the sibling tool.

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

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

The description states a specific verb ('Read') and resource ('a specific message conversation thread with all messages'), which clearly distinguishes it from list_conversations (which lists conversations) and get_post (which reads a post). It doesn't explicitly name a sibling, but the action and resource are clear enough to differentiate.

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

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

The description provides clear context: it reads a specific conversation thread, and it explicitly notes that both school_id and chat_id are required, referencing list_conversations as the source of these IDs. It doesn't explicitly state when not to use it or name alternatives, but the usage context is 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?

With no annotations provided, the description carries the burden. It discloses that the tool returns JSON with school details and staff records, and implies it provides only basic info (via contrast with get_staff_member). It does not mention side effects, auth requirements, or pagination, but for a read-only list operation this is acceptable. The description adds value but leaves room for more 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 concise, using three short sentences plus a simple Args listing. The main purpose is stated first, followed by return format and a pointer to an alternative. It is appropriately sized and front-loaded with the most important information, though the Args section could be integrated more fluidly.

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 it is a simple list tool with a single parameter and no output schema, the description covers the essential return contents (school phone, address, staff records) and distinguishes itself from a more detailed sibling. However, it lacks details on potential limits, error handling, or whether the staff records include only names/roles/phones, which could be inferred but not explicit. It is adequate but not fully complete.

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

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

The schema has 0% description coverage for the single parameter school_id. The description only repeats 'School ID' in the Args section, adding no semantic meaning beyond the schema's type and title. This provides no guidance on format, constraints, or how to obtain the ID, which is a significant gap.

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 specific fields (names, roles, phone numbers). It also explicitly differentiates from get_staff_member by pointing out that tool provides full details. This is a specific verb+resource that distinguishes it 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?

The description explicitly directs users to get_staff_member for full staff details, indicating when not to use this tool. It implies usage when basic contact info and directory are needed. However, it does not mention any prerequisites or conditions beyond that contrast, leaving some ambiguity but still providing clear 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?

With no annotations, the description carries the full burden of behavioral disclosure. It discloses that the tool returns a paginated list of posts with titles, authors, dates, and summaries, and it mentions the page parameter for pagination. However, it does not state whether the operation is read-only (though 'get' implies it), nor does it cover error handling, authentication requirements, or any side effects. The information is adequate but not comprehensive for a tool with zero annotation support.

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. The opening sentence states the purpose, the second notes the return type, the third gives a routing suggestion, and the Args section lists parameters. It front-loads the key purpose and avoids unnecessary fluff. The Args section is slightly redundant with the schema but justified given the schema's lack of descriptions. Overall, it is efficient and organized.

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 main purpose, return content, pagination, and the alternative tool for full details. It does not explicitly differentiate from get_group_feed, nor does it mention any required permissions or error cases. Since an output schema exists (though not shown here), the description need not enumerate return fields, but it does mention the key fields. For a simple list operation, this is largely complete, but the lack of comparison with get_group_feed and any note on authentication leaves a small gap.

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

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

Schema description coverage is 0% (the schema properties have no descriptions), so the description's Args section is the only source of parameter meaning. It provides basic explanations: 'school_id: School ID' and 'page: Page number for pagination (default: 1)'. This adds some value over the bare schema, but the explanations are minimal. For a tool with only two simple parameters, this is sufficient, though it does not elaborate on constraints or formats beyond the obvious.

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 gets recent posts from a school's feed, specifying the content (titles, authors, dates, summaries). It also indicates it returns a paginated list. This is specific enough to distinguish from get_post (which provides full details) and get_group_feed (which is for group feeds), though it does not explicitly name these siblings. The verb and resource are 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 gives one explicit routing instruction: 'Use get_post with the feed_id to see full details.' This tells the agent when to switch to get_post. However, it does not mention when to use get_group_feed or other listing tools, nor does it state any exclusions. The guidance is helpful but incomplete for distinguishing among all sibling feed/list 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 provided, the description carries the full burden of behavioral disclosure. It only repeats the schema's required parameters and tells where to obtain them, but does not describe any behavioral traits such as pagination, ordering, error conditions, or whether the operation is read-only. This is a significant gap for a tool that might return a large feed.

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, starting with the core purpose, then a clearly marked IMPORTANT note and a structured Args list. It avoids verbosity while delivering necessary parameter context. Slight improvement would be possible by merging the redundant required note, but it is well-organized and 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 (indicated by the context signal), the description need not explain return values. It covers the essential parameter origin and requirement. However, it lacks contextual details like pagination limits, ordering, or potential filters, and does not clearly distinguish its scope from sibling tools. For a simple getter this is acceptable but not rich.

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 so by explaining that school_id is the same one used in list_groups and group_id comes from list_groups results, adding practical meaning beyond the bare integer types. This is sufficient for the two parameters involved.

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

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

The description clearly states the tool retrieves posts from a specific group's feed, using a clear verb ('Get') and resource ('posts from a specific group's feed'). It differentiates from siblings like get_feeds (likely for all feeds) and get_post (single post) by specifying the group context.

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

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

The description implies usage by requiring school_id and group_id, and mentions they come from list_groups, which gives context. However, it does not explicitly state when to prefer this tool over alternatives like get_feeds or get_post, nor does it provide exclusions or criteria for selection. The usage guidance is implied rather than explicit.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It explains that image attachments are returned inline and PDF attachments have their text extracted inline, which is meaningful behavioral context beyond a simple fetch. It does not mention error cases or pagination, but for a single-post retrieval tool this is adequate.

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

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

The description is compact and front-loaded with the main purpose, followed by useful attachment behavior notes and a brief Args section. The Args block partly duplicates the schema, but it adds semantic value that the schema lacks, so no sentence is wasted.

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

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

For a single-parameter, no-output-schema, no-annotation tool, the description covers the essential call information: what the tool returns, how attachments are handled, and where the required parameter comes from. It is not exhaustive about response structure or errors, but it 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?

The schema only describes feed_id as an integer with title 'Feed Id', and description coverage is 0%. The description compensates by explaining that feed_id is a 'Post/feed ID' and, crucially, tells the agent where to find it in get_feeds results, which the schema does not convey.

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

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

The description clearly states a specific verb and resource: 'Get full details of a specific post including body text, comments, and attachments.' This distinguishes it from list-style tools like get_feeds and get_group_feed, though it does not explicitly contrast itself with any sibling.

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 useful prerequisite by saying feed_id is 'shown as feed_id in get_feeds results', but it does not explain when to choose this tool over alternatives like get_group_feed or get_conversation. No exclusions or decision rules are provided.

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

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

With no annotations provided, the description must carry behavioral disclosure. It does say returns structured data plus an inline profile photo when available, adding conditional return behavior. However, it omits permissions, authentication requirements, and what happens if the user is not found; these are notable gaps for a non-annotated read 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 short, to-the-point, and the most relevant information (purpose, then prerequisite, then return behavior) appears near the start. The Args block complement the schema, but it adds some redundancy; otherwise no sentence is wasted. It is slightly above average but not perfectly compact.

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 a simple two-parameter getter, and the description gives a workflow to obtain user_id, states the fields returned (email, photo, office), and caveats the profile photo as conditionally present. With no output schema, it explains enough for basic usage. Shortfalls are error or not-found behavior and permission assumptions, though for a read-only detail endpoint this stays primarily 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 description coverage is 0%, so the Args block supplies the only parameter context. It gives terse meaning '('School ID', 'Staff member's user ID (from get_directory results)') and the user_id provenance hint is genuinely useful, but it restates the parameter names without additional constraints, defaults, or allowed values.

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

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

Description states a clear verb ('Get') and a specific resource ('detailed info for a specific staff member') including what details are returned (email, photo, office hours). It is distinct from siblings like list_staff and get_directory because it targets one member's full detail rather than a list or a directory entry.

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 the agent to call get_directory first to find the user_id, then use this tool, which is clear workflow guidance. It does not state when not to use the tool or mention list_staff as an alternative for bulk access, so it falls just short of full when/when-not coverage.

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 behavioral disclosure. It does not state whether this is a read-only operation, whether it requires special admin permissions, whether the student must exist (error behavior), or what happens if the ID is invalid. The phrase 'admin detail' hints at an admin context but does not disclose rate limits, data freshness, or side effects. For a single-record fetch, this is a notable gap.

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

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

The description is compact and front-loaded: the first sentence states the purpose and return fields, and the Args line adds the critical ID provenance. Every sentence earns its place. It loses one point because the field list could be slightly more structured, but it is appropriately sized for a single-parameter tool.

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, so return values are already documented. The description covers the input semantics well. However, with no annotations, the description should also disclose whether this is a safe read operation and any admin-context requirements. The absence of behavioral context makes it minimally viable but not complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains that student_id is the `id` from list_students and equates it to the roster id, which is meaningfully more than the schema's bare 'integer' type. This is exactly the kind of semantic clarification an agent needs to avoid passing the wrong identifier.

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 and resource: 'Get admin detail for one student' and enumerates the fields returned (name, grade, SIS id, linked guardians, classes). This clearly distinguishes it from list_students (which lists students) and get_student_dashboard (which likely returns a dashboard view). It could be slightly stronger by explicitly naming the sibling it is not, but the resource and field list make the purpose 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 implies usage: call this when you need admin detail for a single student, and the Args note tells the agent to use the `id` from list_students. This is useful routing context. However, it does not explicitly state when to prefer get_student_dashboard or list_students, nor does it mention any exclusions or prerequisites beyond the ID source.

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?

There are no annotations, so the description carries the full burden. It only implies a read operation via 'Get' and provides no details about permissions, authentication, side effects, or data shape. This is minimal behavioral disclosure.

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 appropriately short and front-loaded with the key purpose. The 'Args' section is somewhat redundant with the schema but does not add harmful bulk.

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

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

For a tool with no annotations and no output schema, the description is too thin. It gives the result categories but omits return shape, any required prerequisites, and a correct route to obtain a valid student_id. The misleading list_schools reference leaves a critical gap.

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

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

Schema description coverage is 0%, so the description must explain the parameter. It adds that student_id identifies a student and suggests a source for it, but that source is wrong (list_schools instead of list_students). This makes the hint counterproductive.

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 clear verb and resource ('Get student dashboard information') and lists the composed data fields (school, grade, classes, teachers). This distinguishes it from generic lookups like get_student and list_students, though it does not explicitly name a sibling.

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

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

No when-to-use versus alternative guidance is provided. The only usage hint, 'use list_schools to see available students', is misleading because list_schools presumably lists schools, not students; the correct sibling would be 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?

With no annotations, the description carries the burden. It discloses a prerequisite (PS_ENABLE_WRITES), the effect (ParentSquare emails the guardian), and that the same endpoint can resend. This is helpful, but it does not mention potential errors, idempotency beyond 'resend', or any rate limits. It covers the key behavioral traits adequately.

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. It front-loads the purpose, then explains usage and parameters in a compact block. No unnecessary words or repetition. The Args section cleanly lists parameters with short descriptions.

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 simplicity of the tool (2 parameters, no enums, output schema exists), the description covers all necessary aspects: purpose, usage condition, prerequisite, and parameter sources. It is complete for an agent to correctly invoke the tool. The output schema handles return values, so no need to repeat them.

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 provides brief but useful semantics: school_id is a School ID and user_id is the Guardian's user ID, with an explicit source (from list_parents). This adds meaning beyond the bare schema and helps an agent understand where the parameters come from.

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) a ParentSquare registration invitation to one guardian. It specifies the resource (registration invitation) and the target (one guardian), and distinguishes from bulk operations by emphasizing 'one guardian'. The mention of resending also clarifies a specific use case.

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 clear context: get user_id from list_parents and only invite guardians with registered=false. This establishes when to use and when not to (unregistered guardians only). However, it does not explicitly name alternatives like bulk_invite_parents, though it implies single vs. bulk. The guidance is strong but not fully explicit about 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. It discloses that existing links are left untouched, that unlinking is destructive and deferred, and that writes require PS_ENABLE_WRITES. This is meaningful behavioral context beyond 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 compact and front-loaded with the core action, followed by a key behavioral note and parameter explanations. Every sentence earns its place, though the parameter list is slightly redundant with the schema.

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

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

Given the tool's simplicity (3 required integer params, no nested objects) and the presence of an output schema, the description covers the essential context: what it does, what it requires, and what it doesn't do. It could mention the return value, but the 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?

Schema description coverage is 0%, so the description must compensate. It explains each parameter: school_id, user_id (from list_parents), student_id (from list_students). This adds provenance and meaning 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 states a specific verb and resource: 'Link an existing guardian to an additional student.' This clearly distinguishes it from sibling tools like add_parent or list_links. It also clarifies the scope (additional student, not initial creation).

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 notes the requirement PS_ENABLE_WRITES and states that unlinking is deferred to the ParentSquare website, which helps an agent know when not to use this tool. It doesn't explicitly name alternative tools for unlinking, but the context is clear enough.

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

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

No annotations are provided, so the description carries the full burden. It discloses the 'one call' behavior and lists output fields (grades, teachers, room-parent counts), which adds value beyond the schema. However, it does not explicitly state that the operation is read-only, nor does it mention authentication, rate limits, or error conditions. Since 'List' implies a read action, it's not misleading, but the description could be more explicit about safety and performance implications.

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. The first sentence establishes the purpose, the second highlights the one-call behavior, the third links to other tools, and the args list is minimal. Every sentence adds value without redundancy, making it easy for an agent to parse quickly.

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 3 parameters and an output schema, the description covers all inputs, explains the filters, and indicates the return includes section_id for chaining. It addresses potential pagination concerns with 'Returns every class in one call.' It doesn't detail the output schema, but that's fine since an output schema exists. Minor gaps: no mention of error handling or large-data considerations, 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 description coverage is 0%, so the description must compensate. It fully explains each parameter: school_id is sourced from list_schools, name_contains is a case-insensitive substring filter, and grade is a case-insensitive filter with an example ('Kindergarten'). This provides clear semantics that the bare schema lacks, going beyond types and defaults.

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 a school's classes (sections) with grades, teachers, and room-parent counts.' It specifies the resource (classes), scope (a school), and output fields. It distinguishes itself from siblings by noting it returns every class in one call and identifies downstream tools that use the section_id, making it clear when to use this tool.

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

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

The description gives context: school_id comes from list_schools, and the result section_id is used with get_class, edit_class, etc. It also notes 'Returns every class in one call,' implying it's for comprehensive listing. However, it does not explicitly state when NOT to use this tool or name alternatives like list_class_students for filtered/specific needs. The chaining guidance is useful but not a full usage comparison.

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 that the tool lists students for a single class, but doesn't mention whether it returns full student objects or just IDs, whether it includes inactive/withdrawn students, or any pagination/ordering behavior. For a read-only list tool, this is a moderate gap.

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

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

The description is compact: one sentence plus an Args note. It front-loads the purpose and gives the key parameter hint. No wasted words, though the Args section partially duplicates the schema.

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

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

The tool has an output schema, so return values are covered elsewhere. The description covers the essential input (section_id) and its source. It doesn't mention edge cases like empty classes or error conditions, but for a simple list-by-ID tool this is acceptable. The lack of behavioral details (e.g., whether it returns only active students) is the main gap.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain that section_id is a 'Class/section ID (from list_classes)', which adds provenance and meaning beyond the bare schema. However, it doesn't specify the expected format (integer is in schema) or any constraints beyond that. The single parameter is adequately explained for basic use.

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 and resource: 'List the students enrolled in one class.' This clearly distinguishes it from sibling tools like list_students (all students) and add_class_students (mutating enrollment). It doesn't explicitly name a sibling alternative, but the scope is clear enough.

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

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

The description implies usage: call it with a section_id to get students in that class. It doesn't explicitly state when to use this over list_students or get_class, but the 'one class' scoping and the Args note provide adequate context. No exclusions or alternatives are named.

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 carry the behavioral health. While it states 'Returns file URLs', it does not disclose whether the operation is read-only, requires special authorization, or handles availability or pagination. This gives the agent little insight into side effects or assumptions.

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 sharp and to the point, with no extra filler. The opening sentence immediately states what the tool does, and the argument listing is useful, though it adds no new information. It could benefit by moving the Args line directly beneath the purpose, but overall it is appropriately succinct.

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, straightforward output), the description gives a functional starting point. However, it omits potentially important context such as what range of dates is covered, whether the list is paginated, or what types of files/documents are included. With an output schema present, return values are not An issue here, but the usage context remains thin.

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 and a generic label ('school_id: School ID') without adding meaningful guidance. It does not explain how to obtain the school_id, its format, units, or relationship to other data, so added value beyond the schema is nonexistent.

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

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

The description explicitly states 'List files and documents posted for a school', identifying a clear verb, resource, and scope. It differentiates from sibling tools like list_links and list_photos by specifying 'files and documents', making the purpose immediately comprehendible.

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 some usage context by noting that it returns file URLs for download_file, implying when to use it. However, it does not explicitly mention alternatives or give conditions such as 'use get_post to fetch files attached to a single post', so the guidance remains 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?

With no annotations provided, the description carries the behavioral burden. It gives useful context: the tool returns form titles, authors, and dates rather than full content ('Use get_post with the feed_id to see the full form content'), and it notes these forms 'may require parent signatures' — a behavioral trait an agent benefits from knowing. It does not mention side effects, but the description strongly implies a read-only listing 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 three sentences plus an Args block. Every sentence earns its place: it states the action, the output fields, the nature of the forms, and a pointer to the full-content tool. The most important information is front-loaded, and there is no fluff 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?

For a simple single-parameter list tool with an existing output schema, this description is complete. It explains what the tool returns, the type of forms covered, and the next step for full content. The one omission is that it doesn't explicitly mention what the absence of a school_id entails, but the schema marks it required, and the purpose is evident from the text.

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

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

The schema has zero description coverage, so the description must compensate. The only parameter, school_id, is addressed with 'school_id: School ID' in the Args section. This adds little beyond the schema's type and name, but the surrounding 'for a school' phrasing gives some context. It does not explain how to obtain the ID or validate it, so it adds only minimal value for a single obvious 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 uses a specific verb-plus-resource construction: 'List available forms and permission slips for a school.' It also clarifies the result covers titles, authors, and dates, and gives concrete examples of form types (field trip permission, driver forms). This clearly separates it from sibling list tools like list_links or list_signups.

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

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

The description implies when to use it by stating it lists forms and permission slips, and it suggests a follow-up ('Use get_post with the feed_id to see the full form content'). However, it does not explicitly state when not to use it or contrast it with sibling list tools (e.g., list_signups, list_notices). The guidance is present but only implicit.

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

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

With no annotations, the description must disclose behavioral traits. It mentions grades are per-school and discovered at runtime, adding context, but does not explicitly state read-only behavior, permissions, or other side effects. It relies on the verb 'List' to imply read-only.

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, three lines including args, with no extraneous information. It front-loads the purpose and use case.

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 presence of an output schema, the description adequately covers purpose, usage, and parameter semantics. It does not mention error handling or limitations, but for a simple list operation it is reasonably 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 description coverage is 0%, so the description must compensate. The description explains school_id as 'School ID (from list_schools)', which tells the agent where to obtain it, adding value beyond the schema's type integer.

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 a school's grades and returns grade_id values needed for add_student. It uses specific verbs and resources, distinguishing it from sibling tools like list_schools and list_students.

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 that grades are per-school and discovered at runtime, and explicitly directs the user to use the returned grade_id with add_student/edit_student, which clarifies when this tool is appropriate in the 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?

With no annotations, the description carries the full behavioral burden. It discloses that the tool lists groups with active post counts and descriptions, implying a read-only operation, but does not mention pagination, sorting, or any side effects. It adds some context (the relationship to get_group_feed) but lacks explicit statements about read-only guarantees or edge cases.

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

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

The description is short and front-loaded with the primary purpose. It then gives a useful next-step hint and a parameter explanation, all in a compact structure. No superfluous text; 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 presence of an output schema (which defines return shape), the description covers the essential call context: required parameter, how to obtain it, and how to follow up. It doesn't mention limitations like pagination or error handling, but for a simple list tool with one parameter, it is adequately complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that school_id refers to a school ID and directs the user to list_schools to find valid IDs, adding meaning beyond the raw integer type. This is sufficient for the single required 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 states a specific action ('List groups at a school') with a clear object (groups) and key attributes (active post counts and descriptions). It differentiates from siblings like list_class_students or list_schools by being group-specific, so an agent can immediately recognize its unique purpose.

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 on prerequisite steps: how to obtain school_id via list_schools, and how to proceed to view posts using get_group_feed with matching school_id and group_id. It names the relevant sibling and the condition for switching, though it doesn't explicitly state when not to use this tool (e.g., if you need a single group's details).

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 behavioral traits. It mentions that the tool returns link names and URLs, which gives some transparency about output, but it does not state whether the operation is read-only, require any permissions, or have side effects. It also omits details about pagination or error handling. For a tool with zero annotation support, this is insufficient.

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 and to the point, but it includes a redundant 'Args' line that merely echoes the schema. The critical information about the resource type and return content is present, and the structure is reasonably front-loaded with the primary purpose. However, the redundancy reduces efficiency slightly; it could be tightened without losing meaning.

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

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

While an output schema exists (so return structure isn't needed in the description), the definition still lacks guidance on when to choose this tool over its many sibling listing tools. It also does not mention any prerequisites or limitations. For a simple list operation, the purpose is clear, but the lack of differentiation and operational context makes it incomplete for reliable selection.

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%, placing the entire burden on the description. The description only repeats the parameter name and type ('school_id: School ID') without adding any semantic meaning beyond what the schema already provides. It does not explain how the ID is used, what format it should be in, or any constraints. This adds no value over the input 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 tool lists quick-access links for a school, with specific examples (calendars, menus, forms). It identifies the resource type distinctly from siblings like list_files or list_photos, though it does not explicitly name an alternative. The verb 'list' plus resource and scope makes the 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?

There is no guidance on when to use this tool versus other listing tools such as list_files or get_feeds. It does not state exclusions or alternatives, leaving the agent to infer when quick-access links are relevant without any comparison to sibling functions. The description is purely declarative with no 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 are provided, so the description carries the full burden. It indicates a read-only listing operation, but does not explain return behavior, pagination, filtering, authentication needs, or how the listed notices are structured. This leaves the agent with only the word 'list' plus resource categories.

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 and front-loaded, with no filler or promotional language. However, the 'Args' line largely repeats the schema and adds no real value, so it is not perfectly efficient.

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

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

For a simple one-parameter list operation, the description covers the resource and the required parameter, and the output schema presumably covers return shape. However, it lacks usage context, sibling differentiation, and any detail about filtering or special behavior, leaving the agent to infer when and how to invoke it.

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

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

The only parameter explanation is 'school_id: School ID', which simply restates the parameter name and adds no meaningful detail beyond the schema's integer type. The description fails to clarify where to obtain school_id 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 uses a specific verb and resource ('List alerts and notices') and scopes it to a school, with concrete categories (urgent alerts, secure documents, consent forms). It is clear about what the tool does, though it does not explicitly differentiate itself from sibling 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?

There is no guidance about when to use this tool versus sibling tools like list_forms, list_signups, or list_polls. The description only implies that it is for school alerts and notices, but provides no exclusions, prerequisites, or alternative routing.

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

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

With no annotations, the description carries the behavioral burden. It states that the tool returns the full parent roster in one call and supports substring filters, but it does not explicitly mention read-only behavior, ordering, pagination, or invalid-input behavior. This is adequate but has 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 front-loaded with the purpose, followed by the key return behavior and downstream usage, then a clean Args list. Every line 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 required parameter, optional filters, and downstream user_id usage, while the output schema covers return fields. It could note whether filters combine or how results are ordered, but it 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?

The input schema has 0% description coverage, so the description compensates by explaining school_id's source, name_contains as a case-insensitive substring filter, and student_name_contains as a filter on linked student 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 explicitly names the verb and resource: listing guardians/parents on a school's admin roster, and it enumerates the returned fields. This clearly separates it from sibling list tools like list_students and list_staff.

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 clear context for when to use the tool (get the full parent roster in one call) and downstream usage of the returned user_id. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.

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

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

Annotations are absent, so the description carries the full burden. It does not state whether the operation is read-only, how it handles invalid or missing school_ids, whether pagination is involved, or any side effects. It only describes the output content (upcoming/paid counts, total amount, payment posts). For a list tool, read-only behavior is implied but not explicit, and error handling is entirely undisclosed.

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: one sentence stating purpose, one sentence detailing output, and a minimal args line. It is front-loaded with the core action and provides useful output detail without unnecessary fluff. The structure is logical, though the args section could be more informative without hurting conciseness.

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 there is an output schema (though not shown), the description needn't enumerate every field, but it does give a high-level summary of what the tool returns (counts, total amount, payment posts with items/prices). However, it omits important operational context such as possible error conditions (e.g., invalid school ID), ordering of results, or any filtering options. For a simple one-parameter list, this is minimally acceptable but leaves gaps in handling edge cases.

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, school_id, has no schema description (coverage 0%). The description's 'Args' section says 'school_id: School ID', which is purely tautological and adds no semantic value beyond what the property name and integer type already convey. It neither explains the format, constraints, or usage, nor clarifies that it is an identifier for an existing school. The description fails to compensate for the schema's lack of 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 states a specific verb 'List', a clear resource 'payment items', and narrows scope to 'a school', adding 'summary stats and item prices' as the output focus. This distinguishes it from sibling list tools like list_schools or list_links, though it does not explicitly name alternatives. 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?

No guidance is given on when to use this tool versus alternatives, no prerequisites are mentioned, and there is no exclusion or condition to pick another tool. The phrase 'for a school' implies the need for a school_id but doesn't explain when this is the right choice among many list_* siblings. The agent is left 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?

With no annotations provided, the description carries the behavioral disclosure burden. It usefully reveals that the tool returns URLs rather than image content and that those URLs are compatible with download_file. It does not mention pagination behavior, ordering, authorization requirements, or error conditions, though an output schema exists.

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 appropriately short and front-loaded, with the core purpose first, followed by the download_file integration note and a minimal Args list. The Args lines largely duplicate the schema but are brief and do not bloat the description.

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 list tool with an output schema, the description covers the basic purpose, parameter names, and downstream usage. It is not fully complete because it omits any guidance on when not to use it, how pagination behaves beyond the default, or whether authentication/school context is required.

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, but the Args section merely restates what the schema already implies: school_id is a school ID and page is a page number. It adds no meaningful context such as how to obtain school_id, page bounds, or ordering 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 opens with a specific verb and resource: 'List photos posted for a school.' This clearly identifies what the tool does and distinguishes it from download_file by noting that it returns URLs. It does not explicitly contrast with the closely related list_files sibling, so it stops short of full 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 use case is clear: list photos for a school. The phrase 'Returns photo URLs that can be used with download_file' gives concrete downstream guidance on how to use the returned data. However, it does not state when to prefer this over alternatives like list_files, so exclusions are absent.

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 burden of disclosing behavior. It mentions that the tool shows poll questions, options, and vote counts, which gives some insight into the response. However, it doesn't disclose whether this is a read-only operation, whether pagination exists, or how many polls are returned. For a simple list tool with no annotations, this is adequate but not 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 concise, with two sentences explaining what the tool does and what is returned, followed by a clear Args list. No fluff, and the essential information is front-loaded. The structure is clean and easy to parse.

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

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

The tool has an output schema, so return values are already defined. The description provides enough context for a simple list operation with one parameter. It might be missing guidance on edge cases (e.g., no polls available), but for a straightforward list tool with a clear output schema, it 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?

The schema has 0% coverage since no descriptions are provided in the schema properties. The description adds meaning to the school_id parameter by stating it is the 'School ID', which is not in the schema. With only one parameter and no enum constraints, a baseline of 4 is appropriate as the description fully clarifies the parameter's purpose.

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 explains what the response contains (questions, options, vote counts). It is distinguishable from siblings like list_notices or list_signups, which are clearly different entities, though no explicit differentiation is provided.

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

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

The description implies usage: to list polls for a school. It states the required school_id parameter but does not provide any context on when to use this tool versus others (e.g., no mention of alternatives or prerequisites). The usage context is clear but no exclusions or alternatives are given.

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

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

No annotations are present, so the description carries the full burden. It discloses the mechanism (sidebar parsing), per-school variability, and the result shape (list of sections). It does not cover error behavior, but 'List' and 'parsing' make the read-only nature clear.

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 short blocks with purpose front-loaded, illustrative examples, and an Args section. Every sentence earns its place; 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 one-parameter, read-only list tool with an output schema, the description covers discovery, purpose, and parameter provenance. An agent can invoke it correctly based on this description alone.

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

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

The schema has no parameter descriptions (0% coverage), but the Args block compensates: school_id is explained as 'School ID' and the description points to list_schools for valid values. This is actionable beyond the bare integer 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?

States an explicit action ('List features available'), a specific resource ('for a specific school'), and the mechanism ('by parsing its sidebar navigation'). The return value is clearly described as available sections, distinguishing it from data-fetching siblings like get_feeds or get_calendar_events.

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?

Hints at when to use it per-school because 'Different schools may have different features enabled.' It does not name sibling alternatives or exclusions, but the Args section gives a clear precondition by pointing to list_schools for finding valid IDs.

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 present, so the description must carry the behavioral burden. It discloses an important behavior: returns JSON containing schools, students, and the user ID, which helps an agent know what to expect. However, it does not mention pagination, filtering, or potential failure modes, leaving some behavior opaque.

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

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

Three sentences with no filler; the main action and output format are front-loaded. The get_directory pointer is a routing hint that earns its place without bloating the description.

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

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

For a zero-parameter listing tool, the description covers purpose, output contents, and next-step usage. Since an output schema exists and this is a simple operation, nothing critical for invoking 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?

The tool has zero parameters, so schema coverage is trivially complete and the baseline is 4. The description adds value by explaining that the output values, school_id and student_id, are meant to be consumed as inputs by other tools.

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

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

States a specific verb and resource: lists schools and students in the ParentSquare account. This clearly identifies the tool's function, though it does not explicitly differentiate it from siblings like list_students or list_class_students.

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 clear context: use the returned school_id and student_id in other tools, and use get_directory for contact info. It lacks explicit when-not-to-use guidance relative to list_students or list_class_students, but the pointers are 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?

With no annotations, the description carries the disclosure burden. It reveals that the tool returns summaries with title, progress, and author, illustrates the progress format, and notes that detailed items require get_post. It omits auth or pagination-depth caveats, but these are minor for a read-only listing with an output 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 front-loaded with the core purpose, then provides a compact output summary, a useful cross-reference, and a short Args block. It is efficiently sized, though the Args section somewhat duplicates the input schema.

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

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

For a two-parameter list tool, the description plus schema covers the required school_id, optional page, the fields returned, and the follow-up path to get_post. The presence of an output schema covers return shape, so an agent has enough 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 description coverage is 0%, so the description must compensate. It restates school_id as 'School ID' and page as 'Page number for pagination (default: 1)', adding the default but little else. It does not explain page size, response ordering, or how school_id relates to feeds, so it only partially compensates for the absent 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 states a specific verb and resource: 'List sign-up and RSVP posts for a school', with concrete examples such as item donations, volunteer slots, and event RSVPs. This clearly separates it from sibling list tools like list_links or list_notices and from get_post.

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 directs agents to 'Use get_post with the feed_id to see full signup details including individual items', giving a concrete alternative for deeper detail. It does not, however, enumerate exclusions or compare against other list_* siblings, so it stops short of full routing 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 carries the burden. It discloses the return fields and the optional name_contains filter behavior (case-insensitive substring). However, it doesn't mention pagination, ordering, or whether admins are included in the same list or distinguished by role. It's adequate but not 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 front-loaded: the main purpose is in the first sentence, followed by a usage tip and parameter explanations. Every sentence earns its place; no filler.

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

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

Given the tool's simplicity (2 params, 1 required, output schema present), the description covers the essential usage: what it returns, how to use the result, and how to obtain the required parameter. It doesn't mention pagination or sorting, but for a list tool with an output schema, this is a minor gap.

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

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

Schema description coverage is 0%, so the description must compensate. It explains school_id as coming from list_schools and name_contains as a case-insensitive substring filter on staff name. This adds real meaning beyond the raw schema, though it doesn't detail the exact format of the name filter (e.g., wildcards).

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

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

The description states a specific verb ('List'), a resource ('a school's staff and admins'), and the exact fields returned (user_id, name, email, phone, role/title). It also distinguishes itself from siblings like get_staff_member and list_students by focusing on staff/admins. 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 clear context: it lists staff for a school, and explicitly tells the agent to use the returned user_id with add_class_staff. It also references list_schools for the school_id. It doesn't explicitly say when NOT to use it versus get_staff_member, but the context is strong enough for an agent to select it 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, the description carries the burden of behavioral disclosure. It explicitly states 'Returns the full roster in one call', indicating no pagination, and notes that the id from results is intended for use as student_id in other operations. It does not state read-only status explicitly, but 'list' and 'roster' imply it. The description adds meaningful behavioral context beyond the schema, though it could mention ordering or any implicit 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 concise and well-structured: a one-sentence purpose, a behavioral note, and a clean Args list. No filler or redundancy. Front-loads the main purpose and then details parameters 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?

Given the presence of an output schema, the description need not enumerate return fields, yet it does highlight the key fields. It explains parameter sources and chaining behavior. However, it lacks explicit mention of ordering or any limits on the number of students, though 'full roster' implies all. Overall it's complete enough for an agent to invoke correctly, with minor gaps in MS.

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 Args section fully explains each parameter: school_id is sourced from list_schools, grade is an optional case-insensitive filter with an example, and name_contains is an optional substring filter. This adds clear semantics that the schema alone does not provide, effectively compensating for the lack of schema-level 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 states a specific action ('List students') on a specific resource ('a school's admin roster') and lists the fields returned (id, name, grade, SIS id, guardians). It clearly distinguishes from siblings like list_class_students by emphasizing 'admin roster' and 'full roster'. The purpose is unambiguous and not a tautology.

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 some usage context: it returns the full roster in one call and instructs how to chain the resulting id into subsequent tools (get_student, edit_student, etc.). However, it does not explicitly mention when to use this tool instead of list_class_students or other list functions, nor does it state any exclusion criteria. The guidance is implicit through 'full roster' but lacks direct 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?

There are no annotations, so the description must carry the behavioral burden. It does convey that the tool returns logged entries with specific fields and is clearly a read/list operation, but it does not mention ordering, pagination, authorization/ownership limits, or explicitly confirm that no mutations occur. This is acceptable for a simple list tool but leaves 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 concise and front-loaded with the main purpose. It includes a useful list of displayed fields and a minimal args block, with no verbose filler or unnecessary background. Every sentence contributes directly to the basic behavior.

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 one parameter and an output schema, the description is nearly sufficient but still misses minor context: how to source school_id, whether the list is ordered, and how large the result set could be. The presence of an output schema covers return shape, so the remaining gaps are modest.

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, but it only repeats 'school_id: School ID' which adds essentially nothing beyond the schema's property name and type. It does not say where to get the school_id, how to ensure it belongs to the current user, or whether the field carries any further meaning.

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: 'List your logged volunteer hours for a school.' It also identifies the key output fields (month, activity type, notes, hours), and the resource is distinct enough from all sibling list_* tools that an agent can select it without opening the schema.

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

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

The description makes the main use case clear—listing someone's logged volunteer hours for a school—but it gives no explicit guidance on when to prefer this over alternatives, no prerequisite steps (e.g., getting school_id via list_schools), and no exclusions. This is adequate but not a complete usage guide.

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 it excels: it discloses that this is a write operation, requires PS_ENABLE_WRITES, replaces the student's full class list under a global lock, preserves other classes, and handles both halves of the switch atomically. This is exactly the kind of non-obvious behavior an agent needs to know before calling.

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-organized: purpose, prerequisite, safety warning, operational behavior, then parameter semantics. The longer safety block is warranted because the concurrency constraint is critical. Every sentence adds value and the structure makes it 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?

For a mutation tool with no annotations, this is complete: it explains the write requirement, the locking behavior, the exact effect on existing enrollments, and how to achieve add-vs-move semantics. The output schema exists, so return values do not need to be described. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. Every parameter is given real meaning: school_id scopes the classes, student_id is sourced from list_students, to_section_id comes from list_classes, and from_section_id is optional with a clear effect. This is significantly more useful than 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 opens with a specific verb and resource: 'Switch a student from one class to another.' It further clarifies scope by explaining that both halves of the switch happen in a single request and that other classes are preserved, which distinguishes it from sibling add/remove enrollment tools. The purpose is unmistakable even without opening the schema.

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

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

The description gives clear behavioral guidance: never run in parallel with other enrollment writes, and omit from_section_id to add rather than move. It states the PS_ENABLE_WRITES prerequisite and explains when the optional parameter changes the operation. It does not explicitly name sibling alternatives, but the guidance is strong enough for an agent to decide 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?

With no annotations, the description carries full disclosure. It states the PS_ENABLE_WRITES requirement, warns that ParentSquare replaces the full staff list and that concurrent writes can cause unrelated associations to disappear, recommends serialization and verification with a fresh get_class read, and clarifies that everyone else on the class is preserved. This is thorough and candid.

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 focused and front-loaded: purpose first, then a labeled SAFETY section, then usage modes. Every sentence carries operational value; there is no filler. The structure makes critical warnings prominent without burying the core instructions.

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 multiple invocation patterns, the description covers prerequisites, side effects, concurrency risks, parameter semantics, and a step-by-step workflow for a complex scenario (school-wide clearing). An output schema exists, so return details are not necessary here. Nothing needed 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 description coverage is 0%, so the description must explain each parameter and it does: section_id is defined as 'Class/section ID (from list_classes)', user_ids as 'One or more people to remove', and role as 'Remove all holders of this role: TEACHER, ASSISTANT, or ROOM_PARENT'. It also explains how they interact (both to filter by role+user), adding value far beyond the schema.

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

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

The description opens with 'Remove staff or room parents from a class.' This is a specific verb+resource with clear scope. It also distinguishes from the sibling add_class_staff by mentioning it in the safety note, so an agent can tell them apart without opening the schema.

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

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

The description provides explicit when-to-use guidance: it explains the three modes (user_ids, role, both), gives a concrete example for ROOM_PARENT, and instructs on school-wide clearing via list_classes. It also warns against parallel calls with add_class_staff, clarifying the alternative. No ambiguity remains.

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 burden, and it does so thoroughly. It discloses the PS_ENABLE_WRITES requirement, the serialization constraint, the preservation of each student's other classes, and the refusal to empty a class. These details go well beyond a simple mutation statement and reveal important side-effect semantics.

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

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

The description is front-loaded with the core purpose, then safety, then semantics, then argument definitions. Every sentence earns its place, and the warning about parallel writes is prominent and concise. It is appropriately sized for the complexity of the 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?

Despite having no annotations, the description covers the critical invocation aspects: required permission, concurrency constraints, side-effect preservation, empty-class guard, and parameter sources. Since an output schema exists, the lack of return-value detail is acceptable. An agent has enough information to call this tool safely and 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, and it does. It explains school_id as the student's school, section_id as coming from list_classes, and student_ids as coming from list_class_students, which gives the agent provenance for valid values. It also reinforces the required, non-empty nature of student_ids, adding meaning beyond the raw property definitions.

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

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

The first sentence, 'Remove specific students from a class,' states a precise verb and resource, and the qualifier 'specific' distinguishes it from class-wide mutation tools like add_class_students or move_student_to_class. The subsequent guard 'student_ids is required: this tool will not empty a class' further clarifies exact 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?

The description gives clear context: it removes only specific students, preserves other class enrollments, and will not empty a class. It also provides a strong concurrency exclusion: never call it in parallel with other class-staff or student-enrollment writes. It does not explicitly name alternative sibling tools, but the behavioral context is enough to guide correct invocation.

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 must carry the burden. It discloses the write prerequisite, the visibility effect, and the date default. It does not discuss edge cases like idempotency, existing posts under a hidden class, or error conditions, but it does state the core behavioral outcome.

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 purpose sentence, a context sentence, and a clear Args list. Every sentence adds value; no fluff. The front-loaded purpose makes it immediately actionable.

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

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

An output schema exists, so return values are presumably covered. The description covers all required parameters, the prerequisite, and the effect. It could mention more about side effects, but for a visibility toggle it provides sufficient context 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's Args section is essential. It explains each parameter: school_id as 'School ID', section_ids as 'from list_classes', visible as boolean meaning, and date with format and default. This adds meaning beyond the bare schema and 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?

The description states an explicit verb-and-resource pair ('Show or hide classes') and explains the specific audience (staff, parents, students). It also connects to add_class by noting newly created classes start hidden, which distinguishes this tool from other class-related 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?

Gives a clear prerequisite (PS_ENABLE_WRITES) and a concrete scenario: 'a class made with add_class needs this before anyone can see or post to it.' It does not explicitly list alternatives or when not to use it, but the context implies the typical workflow after class creation.

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 explains the trigger (MFA error) and the action (submit code to complete authentication), which is helpful. However, it does not disclose potential side effects, such as whether submitting an incorrect code locks the account, whether the code expires, or what the response contains on success/failure. The description is adequate but not rich in behavioral detail.

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. It front-loads the core purpose in the first sentence, then provides context and parameter details in a clear, scannable format. Every sentence earns its place: the trigger condition, the source of the code, and the parameter explanation. 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?

For a single-parameter authentication tool, the description is nearly complete. It explains the trigger, the parameter, and the goal. The output schema exists, so return values need not be described. The only minor gap is the lack of error-handling details (e.g., what happens on invalid/expired code), but this is not critical for an agent to invoke the 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?

The schema has 0% description coverage, so the description must compensate. It does: it explains that 'code' is the 6-digit verification code from email, adding format (6-digit) and source (email) beyond the schema's bare 'Code' title. This is meaningful semantic enrichment. A score of 4 is appropriate because it fully clarifies the only parameter, though it could have added 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's purpose: submitting a 6-digit MFA verification code to complete ParentSquare login. It uses a specific verb ('Submit') and resource ('MFA verification code'), and it distinguishes itself from the sibling tools, which are all data-retrieval or management operations. The context about when it is used (after an MFA error) further clarifies its unique role.

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

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

The description provides clear context for when to use the tool: when a ParentSquare tool returns an MFA error and a verification code is sent to email. It explains the workflow (check email, submit code). However, it does not explicitly state when not to use it or mention alternatives, though the sibling list makes it obvious that this is the only authentication tool. The guidance is sufficient for an agent to know when to invoke it.

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