add_student

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

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

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

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

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

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

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

For a 5-parameter mutation with no annotations, this is complete: purpose, permission requirement, pre-call workflow, post-call retrieval, return semantics (roster read-back), error/duplication behavior, and all parameter meanings are covered. An output schema exists, so the description rightly does not restate return structure. Nothing an agent needs to invoke this safely and correctly is missing.

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

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

Schema description coverage is 0% — every parameter's meaning must come from the description, and it does. Each of the five args gets a one-line definition: school_id, first_name, last_name, grade_id (with the source list_grades noted), and student_sis_id (marked Optional with its purpose as an SIS/external ID). This fully compensates for the empty schema and adds provenance that the schema cannot express.

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

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

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

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

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

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

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