Teachworks MCP by usefulapi

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds the meaningful constraint that the lesson must still be Scheduled, but says nothing about what makes the operation destructive, duplicate-student behavior, or failure modes.

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

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

A single sentence, front-loaded with the WRITE marker and the operation, followed by the endpoint. Nothing 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 simple two-parameter write with no output schema, the definition covers purpose, precondition, and endpoint. It leaves unaddressed what happens when the lesson is not Scheduled or the student is already enrolled, which is a modest but real 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 100% with only two required parameters (lesson_id, student_id), so the schema already carries the semantics. The description adds no syntax, format, or constraint detail beyond it, making 3 the correct baseline.

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 gives a specific verb+resource ('add a student to an existing lesson') plus a state precondition and the underlying endpoint, so an agent can distinguish it from create_lesson or get_lesson at a glance.

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

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

It states a clear precondition for use ('the lesson must still be Scheduled'), which tells the agent when the call is valid. It does not name alternatives or say what to do when the precondition fails, so it stops short of full when/when-not 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the 'WRITE:' label is largely redundant. The description does add genuine non-annotation context: the family is billed for this student's lessons, and the family must pre-exist. It says nothing about permissions, duplicate handling, or side effects on billing records, which matters for a destructive:true 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?

One tightly-packed sentence plus the HTTP endpoint. The operation type leads, the resource follows, and the billing consequence is included without padding. Nothing 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 15-parameter, non-idempotent, destructive create with no output schema and only 27% schema coverage, the description is thin. An agent gets the core relationship but no guidance on the many optional association fields or on how to recover from a failed/duplicated call.

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 only 27% across 15 parameters, so the description is expected to compensate and does not. Beyond the family association, it explains none of the optional fields (grade, school, status enum, default_service_ids, default_teacher_ids, standard_subject_ids, default_location_id), leaving many linking parameters undocumented in both places.

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 ('create a child student') plus scope ('under an existing family'), which separates it from teachworks_create_family. The parenthetical about the family being billed clarifies the resulting relationship. It stops short of explicitly contrasting with other create_* siblings, so a 4 rather than 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 phrase 'under an existing family' communicates a real prerequisite (the family must already exist), which is useful implied usage guidance. However, there is no explicit when-to-use/when-not-to-use statement or pointer to alternatives such as teachworks_create_family or teachworks_add_student_to_lesson.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The 'WRITE:' prefix and endpoint add mild context, but the description does not elaborate on the destructive implication, auth requirements, or side effects of creating this parent profile.

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

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

Three tight clauses with the operation type ('WRITE:') front-loaded followed by the domain definition and the sibling follow-up. Every sentence earns its place with no filler.

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

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

For a 12-parameter write tool with no output schema and merely 33% schema coverage, the description explains the entity and workflow adequately but leaves most parameter semantics undocumented. The safety profile is carried by annotations, but parameter guidance is thin for a tool of this size.

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 only 33% (4 of 12 parameters documented), which is below the 50% threshold, so the description must compensate but does not. It offers no parameter guidance, omitting even the required first_name/last_name and the status enum's 'Prospective' lead 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?

States a specific verb+resource ('create a family customer') and defines the novel domain entity as 'the billed parent profile that child students belong to'. It distinguishes itself from sibling teachworks_create_child_student by naming it and clarifying the ordering relationship.

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 clear workflow context: add children afterwards with teachworks_create_child_student, and the endpoint POST /customers/family. It stops short of explicit when-not conditions or prerequisites (e.g. required permissions), so it is slightly below the top tier.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the agent knows this is a non-idempotent write. The description's 'WRITE:' prefix largely restates that, and it adds only the conflict-checking advice; it does not explain side effects such as calendar conflicts, notification behavior, or what happens on retry.

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 sentences with the write nature and the resource front-loaded, then the precondition, then the endpoint. Nothing is wasted, though 'POST /lessons' is mild filler for an agent that already has the tool selected.

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 12-parameter mutation tool with no output schema, the description covers the core intent and one important precondition, but omits notable behaviors: group-lesson semantics tied to `spaces`, whether the response returns a new lesson id, and how defaults (name, to_date, time_zone) are resolved.

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 92%, so nearly every parameter is already documented, including defaults and formats (guarded times, dates, time_zone). The description's phrase 'one or more students with a teacher, service and location' loosely maps to student_ids/employee_id/service_id/location_id but adds no new semantics, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('schedule a single lesson on the calendar') plus the key entities involved (students, teacher, service, location). It is immediately distinguishable from siblings like teachworks_add_student_to_lesson or teachworks_create_payment.

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 the agent to call teachworks_list_availabilities and teachworks_list_lessons first to avoid conflicts, which is real operational guidance. It stops short of naming when NOT to use this tool (e.g., adding a student to an existing lesson) or stating the precondition that a lesson would otherwise be double-booked.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context not in the annotations: that this is bookkeeping-only and does not charge a card, which prevents the agent from mistaking it for a payment processor. It stops short of warning about duplicate submissions or required permissions.

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

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

One sentence plus an endpoint, front-loaded with the WRITE classification and the key caveat. Every element earns its place with 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?

With no output schema, the description need not explain return values, and it resolves the main ambiguity (this records rather than charges). It is slightly thin on the mutation's irreversibility and duplicate-submission risk, which matter given destructiveHint=true and idempotentHint=false.

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 80%, so the schema already documents date, amount, customer_id, description, and the payment_method enum. The description adds no parameter syntax, format, or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('record a payment'), prefixes it as WRITE, and clarifies scope with 'bookkeeping only — it does not charge a card'. This quickly separates it from get_payment/list_payments, though it does not name any sibling explicitly.

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 'WRITE:' marker and the 'does not charge a card' note imply when this tool is appropriate (recording already-received funds rather than processing payment), but there is no explicit when-not guidance or named alternative such as get_payment or list_payments.

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?

readOnlyHint=true already establishes this as a safe read, so the description needn't restate safety. It adds useful context about the returned payload shape (contact details and custom fields), but says nothing about not-found behavior, errors, or permissions.

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

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

Two short sentences with no filler; the what-it-does statement is front-loaded and the endpoint notation follows compactly.

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

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

For a simple single-parameter read tool with no output schema, the description sufficiently covers what is fetched and the resource identity. Minor gaps around error/empty results remain but are not required for correct invocation.

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

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

Schema description coverage is 100% with a single required customer_id, so the schema fully documents the parameter. The description only echoes the identifier via the GET /customers/{id} path, adding no new semantics such as accepted ID forms.

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 (Retrieve) and resource (one customer), and clarifies that a customer is a family or independent student plus what is returned (contact details, custom fields). It implicitly contrasts with the singular-vs-list sibling teachworks_list_customers through 'one customer', but never names an alternative explicitly.

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?

Usage is only implied by 'Retrieve one customer' plus the REST path, so an agent can infer this is a by-id lookup. No guidance is given on when to prefer this over teachworks_list_customers, teachworks_get_student, or teachworks_get_employee, and no prerequisites are stated.

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

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

readOnlyHint=true already establishes this as a safe read. The description adds useful context beyond that: it discloses the returned fields (contact details, subjects, wage type, bio, permissions) and the underlying endpoint, which helps the agent anticipate the payload.

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

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

A single compact sentence with the resource and returned fields front-loaded, plus the endpoint. Every element earns its place with no padding.

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

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

With no output schema, the description helpfully enumerates the key fields returned, covering most of what an agent needs to decide on and use the tool. A note on behavior for missing/invalid ids would round it out.

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

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

Schema description coverage is 100% for the single employee_id parameter, so the schema carries the load. The description adds no additional format or semantic detail, matching the baseline 3 for well-documented schemas.

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

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

The description names a specific verb and resource ('Retrieve one employee') and clarifies the entity scope as 'teacher or staff'. This implicitly distinguishes it from list_employees, though it doesn't explicitly name the sibling it contrasts with.

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?

Usage is implied by 'one employee' and the GET /employees/{id} endpoint, signaling a single-record lookup by id. However, there is no explicit when-to-use guidance or comparison against get_employee_earnings or list_employees.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully adds the API path (GET /employees/{id}/earnings) and the earnings breakdown categories, but says nothing about permission requirements, default date-range behavior, or aggregation semantics beyond the labels.

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

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

A single well-formed sentence followed by the endpoint path — front-loaded and free of padding. The path is arguably redundant with the name, but it is compact and harmless.

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

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

With no output schema and a read-only simple tool, the description largely carries the return-shape burden by enumerating the breakdown categories (lessons, other events, other compensation, total). It stops short of explaining default date range or currency/rounding behavior, leaving 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 100%, so all four parameters (employee_id, status, date_from, date_to) are already documented, including the status enum. The description only restates the existence of status and date filtering without adding format or defaulting semantics, so the baseline 3 applies.

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

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

States a specific verb+resource with clear scope: total earnings of one employee, broken into lessons, other events, other compensation, and total, with optional status and date filters. This distinguishes it from teachworks_get_employee (the employee record), though it never names that sibling explicitly.

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?

Usage context is implied by 'for an optional lesson status and date range' — the agent can infer this is a filtered earnings lookup. However, there is no explicit when-to-use vs. teachworks_get_employee or teachworks_get_lesson_totals guidance, and no stated behavior when the optional filters are omitted.

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?

readOnlyHint=true already establishes the safe-read profile, so the annotation carries the main behavioral burden. The description adds useful content-level context (that line items, taxes and totals are returned) and the underlying REST endpoint, but says nothing about permissions or error 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?

Two compact sentences, front-loaded with the core purpose and followed by the endpoint. No filler or redundancy; every clause 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?

There is no output schema, so the description carries the return-value burden and does so at a summary level (line items, taxes, totals). For a simple single-entity read with full param coverage, that is nearly complete, though it omits nested detail and error semantics.

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

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

Schema coverage is 100% (the single invoice_id is documented in the schema), so baseline is 3. The 'GET /invoices/{id}' text maps the parameter to a path variable but adds no format or constraint detail beyond what anyOf/pattern already 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 states a clear verb ('Retrieve') and resource ('one invoice') and enumerates what comes back (line items, taxes, totals). It implicitly contrasts with teachworks_list_invoices by specifying a single invoice, but never names the sibling explicitly.

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?

Usage is only implied: 'one invoice' and the /invoices/{id} path suggest this is the single-record fetch versus the list tool, but there is no explicit when-to-use or when-not-to-use guidance and no alternative is 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?

Annotations declare readOnlyHint=true, so the safety profile is already covered. In exchange, the description adds real behavioral context by disclosing what the response contains (students, statuses, charges, notes, teacher, wage, cost) — valuable since there is no output schema. It stops short of noting failure modes for a non-existent id, which keeps it from a 5.

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

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

One sentence that front-loads the verb and payload summary, followed by the HTTP route. Zero filler; every clause carries information.

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

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

For a single-record GET with one required id and no output schema, the description supplies a useful return-field inventory so the agent knows what it will get. Missing only edge-case behavior (unknown id, permissions), which is minor at this 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?

Only one parameter, and the schema already documents it at 100% coverage ('Lesson id.'). The description adds no format, range, or lookup guidance beyond what the schema provides, so 3 is the correct baseline.

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 ('Retrieve one lesson') and enumerates the payload (participants, teacher, wage, cost). The singular object makes it distinguishable from teachworks_list_lessons and the breakdown distinguishes it from teachworks_get_lesson_totals, though neither sibling is named explicitly.

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?

Usage is implied by the required lesson_id and the single-record framing: use this when you already know which lesson you want. There is no explicit when-to-use statement, no mention of when to prefer list_lessons or get_lesson_totals instead, and no prerequisites.

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

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

readOnlyHint=true already covers the safety profile, and the description adds the return-shape behavior: results are grouped by status, and earnings are restricted to employees. That grouping behavior is not derivable from the schema, so it adds real value beyond the annotations.

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

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

A single dense sentence front-loads the resource and measures, closing with the underlying endpoint. There is mild redundancy with the schema's own enum descriptions, but nothing 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?

With six parameters and no output schema, the description does enough: it names the three kinds, the three measures, the default, the employees-only restriction, and the status/date filters. Only the shape of the returned breakdown remains implicit.

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

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

Schema description coverage is 100%, so every parameter (id, kind, status, measure, date_from, date_to) is already documented in the schema. The description largely restates enum values and the count default without adding format or edge-case detail, so the baseline of 3 applies.

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

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

States a specific verb+resource: aggregated lesson totals per student/customer/employee, with explicit measures (count, duration, earnings). This distinguishes it from listing tools like teachworks_list_lessons, though it does not name the overlapping sibling teachworks_get_employee_earnings.

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 (aggregate totals rather than individual lessons, optional status/date filtering) but never states when to prefer this tool over alternatives such as teachworks_get_employee_earnings or teachworks_list_lessons. Context is present, but no exclusions or 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?

readOnlyHint=true already tells the agent this is a safe read, so the description doesn't need to restate that. It does add useful behavioral value by disclosing that the response includes related refunds and allocation invoices, but says nothing about 404 behavior, permissions, or auth requirements.

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

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

Two short sentences, front-loaded with the substantive operation and followed by the endpoint reference. Nothing is padded or 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?

With no output schema, the description usefully compensates by naming the returned aggregates (refunds, allocated invoices). For a simple single-resource read with a fully documented one-parameter schema, that covers the essentials; error and permission context would be the only additions.

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

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

Schema description coverage is 100% for the single payment_id parameter, so the schema already carries the naming and numeric/string-id semantics. The trailing 'GET /payments/{id}' only confirms that the id is a path parameter, adding little 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?

States a specific verb and resource (retrieve one payment) and even enumerates what comes back with it (refunds, allocated invoices). The singular 'one payment' implicitly separates it from the sibling teachworks_list_payments, though no sibling is named explicitly, which keeps it 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?

Usage is only implied: an agent infers this is the by-id fetch to use when it already has a payment_id. There is no statement of when to prefer this over teachworks_list_payments, and no prerequisites or exclusions are mentioned.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral content by enumerating the field groups returned (contact details, school/grade, billing, custom fields, default teachers/services), which matters because there is no output schema. It omits any note on not-found behavior or permissions, keeping it from a 5.

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

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

One sentence plus the endpoint reference, front-loaded with the verb and resource and zero filler. Every clause (returned field groups, endpoint) carries information.

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

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

With no output schema, the description usefully summarizes the returned profile contents, and readOnlyHint covers the safety dimension. For a single-parameter read tool this is close to complete; only not-found/error behavior is unaddressed.

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

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

Schema description coverage is 100% and there is a single student_id parameter already fully documented, so the baseline is 3. The description adds no format or constraint detail beyond what the schema provides (the accepted integer/string-digits pattern).

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 (Retrieve) and resource (one student profile) and even names the endpoint, so an agent can distinguish it from list_students and from the other get_* siblings. It enumerates the data categories returned (contact, school/grade, billing, custom fields, default teachers/services). It stops short of explicitly naming the sibling it is not, so it falls just under 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 singular 'one student profile' and the required student_id imply this is the lookup-by-id path rather than the list path, but there is no explicit statement of when to use this over teachworks_list_students or teachworks_get_customer. Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds that results are 'weekly' availability slots with day/time fields, which is useful content context. It does not add behavioral detail beyond that (e.g., that results are paginated), and the trailing 'GET /availabilities' mostly restates the read-only annotation.

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

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

Three short, front-loaded sentences with no filler; the purpose, usage cue, and endpoint are each stated once. Nothing could be removed without losing information.

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

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

For a simple read-only list tool with fully-covered schema and no output schema, the description supplies both purpose and return-content shape ('day of week + start/end time') and a usage cue, leaving little an agent needs. Only the lack of any pagination note keeps it from being 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 100%, so all five parameters (day, page, per_page, direction, employee_id) are already fully documented in the schema. The description's mention of 'day of week' loosely maps to one param but adds no format or default detail beyond what the schema provides, so the baseline 3 applies.

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

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

'List teachers' weekly availability slots (day of week + start/end time)' uses a specific verb and resource and even sketches the data shape. No sibling tool deals with availability, so it stands cleanly apart from teachworks_list_employees and the 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?

'Use before scheduling a lesson' gives a concrete use context that tells the agent when this call is relevant. It stops short of naming alternatives or exclusions, but for a uniquely-purposed list tool that is a minor gap.

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

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

Annotations declare readOnlyHint=true, so safety is covered. The description goes further by disclosing what comes back (contact details, status, last invoice date) and the underlying endpoint (GET /customers), which is real added value for a tool with no output schema. It omits pagination behavior, but the schema covers page/per_page defaults.

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

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

Two short sentences, front-loaded with the operation and the domain definition, closed with the endpoint for API mapping. No filler.

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

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

For a 13-parameter list tool with no output schema, mentioning returned fields is the right instinct and partly fills the gap. But it stays silent on the undocumented filter parameters (location fields, pagination semantics) that an agent would need to use the tool well.

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 62% across 13 parameters, and the description names no parameter at all — only 'status' appears, and only as a returned field, not as a filter. With roughly a third of parameters undocumented and no compensating text, the description adds essentially nothing 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?

Specific verb (list/search) plus resource (customers), and it defines the domain term: 'the billed profiles: families (with child students) and independent students.' That definition implicitly separates it from teachworks_list_students, though no sibling is named explicitly.

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?

Usage is implied by 'List or search customers' and the searchable field coverage, but there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as teachworks_get_customer for a single lookup or teachworks_list_students for student-level data.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's disclosure burden is lighter. It adds the underlying endpoint (GET /employees) and the kind of data returned, but says nothing about pagination behavior, result set size, or sorting, which matter for an 11-parameter list endpoint.

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

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

A single front-loaded sentence stating scope and attribute coverage, with the endpoint appended compactly. No filler, though the bare 'GET /employees' line is marginally redundant for an agent.

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 an 11-param search endpoint with no output schema, the description is adequate on identity but silent on the filtering dimensions that define search (geo, status, sorting) and on result pagination. Not misleading, but an agent gets most of its operational detail from the schema 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?

Schema description coverage is 64%, with page, email, subject, per_page, direction, and name filters documented in-schema. The description loosely references 'subjects, status and wage settings' but adds no syntax or meaning beyond the schema, and the undocumented zip/city/state params are left unaddressed. Baseline 3 is appropriate.

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

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

The description names a specific verb+resource ('List or search employees') and clarifies the domain scope ('teachers/tutors and administrative staff'), plus the attribute space involved ('subjects, status and wage settings'). It clearly reads as the collection counterpart to the singular get_employee sibling, but it never names an alternative tool to distinguish itself.

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

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

'List or search' implies when the tool applies, and the mention of subjects/status hints at filter dimensions, but there is no explicit when-to-use guidance, no exclusions, and no routing to related tools like get_employee or get_employee_earnings.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the returned field set (customer, number, dates, status, totals), the status vocabulary, and the underlying GET /invoices endpoint, but says nothing about pagination behavior or result volume beyond what the schema covers.

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

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

Two compact sentences that lead with what the tool lists before the filter axes and endpoint. No filler, though the field/status enumeration is partially redundant with the structured 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?

With no output schema, the description usefully names the fields returned, and it covers all filter dimensions for a 10-param read-only list tool. The remaining gap is pagination expectation (page/per_page defaults live only in the 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 90%, so the schema already documents each filter's semantics, including the useful due_to overlap hint. The description restates the filter axes and the status enum without adding format or syntax detail, so it stays at the baseline.

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

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

States a specific verb (List) and resource (invoices) and enumerates the returned fields plus filterable dimensions, which distinguishes it from teachworks_get_invoice for a single invoice. It stops short of explicitly naming the sibling alternative, so it is clear but not fully differentiated.

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 listing filter dimensions (customer, status, invoice/due date range), so an agent can infer when to apply it, but there is no explicit when-to-use vs get_invoice guidance and no stated exclusions or prerequisites.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It does add useful detail (the fields each lesson carries and the underlying GET /lessons endpoint) but says nothing about pagination behavior, result size, or what happens with deleted/series records even though page/per_page/include_deleted/series_id exist.

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 sentences, front-loaded with purpose, then filters, then endpoint. No filler and nothing repeated verbatim from 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?

With no output schema, the description usefully enumerates the returned fields, and annotations cover the safety profile. For a 17-parameter listing tool it is largely complete, though it omits pagination and sort behavior that an agent would want to know.

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 94%, so the schema already documents nearly all 17 parameters, including the subtle date_from vs from_date vs date_to and location_id vs location_or_parent_location_id distinctions. The description only repeats high-level filter categories, adding no meaning beyond the schema — the baseline 3.

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

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

States a specific verb (List) and resource (lessons), and enumerates the fields returned (teacher, service, location, start/end, duration, status, participants) plus the supported filters. It is clearly the collection counterpart to teachworks_get_lesson, but it never names a sibling, so differentiation is implicit rather than stated.

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 filter list implies when this tool is useful (browsing/searching lessons by criteria), but there is no explicit when-to-use guidance and no mention of alternatives such as teachworks_get_lesson for a single lesson or teachworks_list_other_events for non-lesson calendar items.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine domain context by disclosing that results include nested sub-locations (rooms), which is not visible from the annotations or the flat parameter list. It does not address pagination behavior or result volume, so credit stops at 3.

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

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

Two tight sentences with no waste: the substantive scope detail comes first and the endpoint reference is a compact trailing detail. Nothing is padded or repeated from the title.

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

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

For a simple read-only list tool with fully documented parameters this is close to sufficient, but with no output schema the description could have sketched the returned shape (id, name, nested rooms) rather than only the endpoint. The hierarchy hint is helpful but leaves the payload to inference.

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

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

Schema description coverage is 100% and each of the four parameters (name, page, per_page, direction) is documented inline with defaults and constraints. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

Names a specific verb and resource ('List locations') and adds useful domain detail that locations include sub-locations (rooms) where lessons take place. This distinguishes it from the other list_* siblings by resource, though it does not explicitly contrast with any named alternative.

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?

Usage is only implied: an agent can infer this is the tool to enumerate venue/room data before creating or scheduling lessons. There is no explicit when-to-use, no mention of the name filter as a lookup path, and no stated 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully adds that each event carries location, times and participants, but says nothing about pagination behavior despite the page/per_page/direction parameters in the schema.

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

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

Two compact sentences with the resource and scope front-loaded, followed by the return shape. No filler or redundancy.

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

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

For a read-only, nine-parameter list endpoint with a fully documented schema and no output schema, the description covers the essentials. It could note pagination or filtering behavior, but nothing an agent needs to invoke 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 100% and every parameter (page, per_page, date_from/to/from_date, series_id, employee_id, location_id, direction) is documented in the schema itself. The description adds no filtering or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (List) and a precisely scoped resource (non-lesson calendar events), enumerating examples (meetings, open houses, staff work) and noting the returned fields. The 'non-lesson' framing immediately distinguishes it from the teachworks_list_lessons 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 'non-lesson' qualifier implies when this tool applies versus list_lessons, but no explicit routing or exclusion guidance is given. There is no statement about prerequisites or when NOT to use it, leaving the contrast 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?

readOnlyHint=true already tells the agent this is a safe read operation, so the description needn't re-establish that. It does add value by disclosing the underlying 'GET /payments' endpoint and the shape of returned records (amount, method, date, refunds, invoice allocations), but says nothing about pagination behavior or result volume beyond what the schema implies.

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 compact fragments, purpose front-loaded, no filler. Every clause earns its place and the returned-field list is kept in parentheses rather than bloating the sentence.

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

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

For a simple read-only list tool with no output schema, the description usefully enumerates the fields returned and the filter dimensions, and annotations cover the safety profile. It is nearly complete; only pagination semantics and sort/filter interaction are left unstated.

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

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

Schema description coverage is 100% with all six parameters documented (page, per_page, date_from, date_to, direction, customer_id), so the schema carries the full parameter burden. The description's mention of customer and date-range filtering only gestures at two of these and adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List customer payments') and enumerates the returned fields, which makes the read-only listing intent unambiguous. It doesn't explicitly differentiate itself from siblings like teachworks_get_payment or teachworks_create_payment, but the 'List' verb plus filtered scope distinguishes it implicitly.

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 says 'Filter by customer and date range,' which implies when the tool is useful, but it never states when to prefer it over teachworks_get_payment or teachworks_list_invoices. Usage context 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the shape of the return data ('default cost and wage'), which matters because there is no output schema, and by noting the underlying GET /services endpoint.

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

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

Two short sentences, front-loaded with the resource and its meaning; every clause carries information. The trailing 'GET /services' is largely redundant with the tool name and adds little for an agent, keeping it short of 5.

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

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

For a read-only list tool with annotations covering safety, a fully documented schema, and no output schema, this covers the essentials and even names the returned fields. It omits only pagination/response-shape detail that an agent might want for large catalogs.

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

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

Schema description coverage is 100%, so all four parameters (name, page, per_page, direction) are already documented with defaults and bounds in the schema. The description adds no filtering, pagination, or sorting semantics beyond that, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('List services') and clarifies the domain term by equating services with lesson types like 'Math Tutoring', plus what each record contains (default cost and wage). It is clearly distinct from siblings such as list_lessons or list_subjects, though it never explicitly contrasts with them.

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

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

Usage is implied by the verb and resource — an agent can infer this is the tool for enumerating the service catalog — but there is no explicit when-to-use, when-not, or pointer to an alternative (e.g., for fetching one service or filtering lessons by type).

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

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

The readOnlyHint annotation already establishes this as a safe read. The description adds the 'GET /students' endpoint and, more usefully, enumerates the returned fields (school, grade, subjects, status, billing method, default teachers), which partially compensates for the absence of an output schema. It says nothing about default page size, max per_page, sort order, or how filters combine.

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

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

A single front-loaded sentence plus the endpoint reference; there is no filler. Minor redundancy in 'List or search' and the endpoint string echoing the already-annotated read-only nature, but nothing wasteful.

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 13-parameter, zero-required list tool with no output schema, the description gives a reasonable field inventory but omits pagination behavior, default ordering, and any statement that filters are combinable/optional. Adequate but with clear gaps an agent would have to discover from the schema 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?

Schema description coverage is 92%, so the schema already documents nearly every filter (page, type, email, grade, school, status, subject, name, customer_id, phone_number, direction). The description adds no format or semantics beyond naming a few of the same fields, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List or search students') and clarifies the two student kinds it covers (child students of families and independent students). It also enumerates the fields carried in the response, so an agent knows what a student record contains. It stops short of naming any sibling (e.g. teachworks_get_student or teachworks_list_customers) to disambiguate when a single-record lookup is wanted 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?

'List or search' implies the two modes of use (browse vs. filter), and the field list hints at what can be searched on. However, there is no explicit when-to-use guidance, no mention of the sibling teachworks_get_student for single-student retrieval, and no note about paginating through large result sets.

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?

readOnlyHint=true already establishes this as a safe read. The description adds that subjects are 'standard' (i.e., a fixed reference list) and the backing endpoint, which is modestly useful context, but says nothing about pagination behavior or result shape.

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

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

Two tight clauses with zero filler and the resource front-loaded. The trailing 'GET /subjects' is implementation detail but cheap to include and mildly useful for troubleshooting.

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 no-argument read tool with annotations covering safety, the definition is adequate. However, with no output schema, it does not say what a subject record contains or how pagination results are shaped, leaving a modest 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 100%, so name, page, per_page, and direction are all fully documented in the schema. The description adds no parameter detail beyond that, which matches the baseline 3 when the schema carries the burden.

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

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

States a specific verb (List) and resource (standard subjects), plus where they are used (student and teacher profiles). This clearly distinguishes it from the other list_* siblings (services, locations, lessons), though it doesn't name any alternative explicitly.

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 or when-not-to-use guidance, and no mention of alternatives such as list_services. The parenthetical 'used on student and teacher profiles' hints at context but stops short of telling the agent under what circumstances to call this tool.

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