delegation-school

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 passing advances and failing reteaches, and that reflection improves the course. It does not cover permissions, reversibility, or side effects, making it adequate but not detailed.

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, front-loaded with purpose. Every sentence adds unique value, with no redundant or extraneous 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 4-parameter tool with no annotations and no output schema, the description provides solid purpose, usage, and parameter semantics. It lacks mention of outputs or error handling, but is largely complete.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining the semantics of passed (advance/reteach) and reflection (signal for improvement), going beyond the schema.

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

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

The description clearly states the verb 'Record a lesson result' and the resource 'for a learner'. It specifies the context 'AFTER grading its quiz/assignment', distinguishing it from sibling tools like get_lesson or list_lessons.

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

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

The description explains when to use the tool (after grading) and how the passed flag affects advancement. It also advises including reflection when available. However, it does not explicitly mention when not to use this tool or alternatives.

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

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

No annotations provided, so description bears full burden. It implies read-only ('usage snapshot', 'inspectable state') but does not explicitly state that it does not modify state. Could be clearer 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?

Single sentence front-loaded with 'OPERATOR / Inspectable State' followed by specific data points and usage context. Every part adds value with no wasted words.

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

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

For a simple tool with 1 parameter, no output schema, and no nested objects, the description covers overall purpose and usage context adequately. Could add return format details but not critical.

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% with admin_key description already present. Description adds no extra parameter semantics beyond restating the requirement. 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 clearly states the tool returns a 'usage snapshot' with specific data points (learner count, level mix, completions, per-lesson pass rates, recent reflections), distinguishing it from siblings like list_lessons or overview.

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

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

Explicitly states the tool requires admin_key and serves operator agents answering 'what is the state of the work?', providing clear context. No explicit when-not or alternatives, but sufficient for its role.

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. Only states 'get' – a read operation – but omits any behavioral traits like idempotency, auth requirements, or side effects. Minimal 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?

Two sentences: first states core function, second provides usage guidance. No extraneous content, front-loaded.

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

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

Given no output schema and simple single-param input, description covers purpose, usage, and parameter origin. Lacks details on markdown structure or limitations, but adequate for the tool's simplicity.

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

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

Schema coverage is 100% with slug description. Description adds meaningful context about slug's origin (from list_lessons/start_session), enhancing understanding beyond schema.

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

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

Clearly states it retrieves the full markdown of a lesson by slug, with a pedagogical usage hint. Distinguishes from siblings like list_lessons (listing) and complete_lesson (completing).

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

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

Explicitly says to use with a slug from list_lessons/start_session, implying when to use. Could better exclude alternatives, but provides actionable 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, description must disclose behavior. It mentions returned fields and optional filter but omits details like pagination, default ordering, or if all lessons are returned. Adequate but not fully 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?

Single sentence, 15 words, front-loaded with key information. No wasted words; efficient and clear.

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 simple tool (1 optional param, no output schema), description covers core purpose and parameters. Could mention result ordering or size limits but overall 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 has one parameter (track) with enum and description. Description adds value by listing the exact fields returned, complementing the schema's minimal parameter description.

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 lessons with specific fields (slug, title, track, order, summary) and optional track filter. Distinguishes from sibling tools like get_lesson (single lesson) and complete_lesson (action).

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?

Describes optional filtering but does not provide when-to-use versus alternatives like get_lesson or search. No explicit guidance on when not to use this tool.

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

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

No annotations provided, but the description makes it clear this is a read-only informational tool with no side effects. Adequate transparency for a zero-parameter 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?

Extremely concise, front-loaded, and every word adds value. No unnecessary information.

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

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

For a simple info tool with no parameters and no output schema, the description fully covers what the agent needs to know to decide 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?

No parameters exist, so schema coverage is 100%. Description adds nothing beyond schema, but that is acceptable; 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 clearly states what the tool provides: an overview of delegation.school, the three tracks, and how to run the course as a tutor. It distinguishes itself from sibling action-oriented tools by being background reading.

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 'background reading', which implies when the agent needs general orientation rather than performing actions. No when-not or alternatives listed, but context with sibling tools makes it clear.

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

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

No annotations are provided, so the description carries the full burden. It discloses the effect ('routes through the learner's record so the change sticks'), authentication needs ('Requires admin_key'), and a prerequisite ('must have started a session first'). However, it does not mention whether the operation is irreversible, any rate limits, or what happens on failure.

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 sentences that are front-loaded with the purpose and example, followed by prerequisites and authentication. Every sentence adds necessary information without redundancy. This is excellent structure for an AI 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?

Given no output schema, the description should hint at return values or success/failure indicators. It does not. It covers inputs and behavior adequately, but the lack of return-type information is a gap. The prerequisite and authentication details partially compensate.

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% (all three parameters have descriptions). The description adds value by clarifying that 'learner' uses the same key as in start_session and that 'admin_key' is the 'Worker secret ADMIN_KEY'. It reinforces the enum values for 'level' with examples. This extra context goes beyond the schema alone.

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: 'reclassify an existing learner's track (scratch | intermediate | power).' The verb 'reclassify' combined with the target resource (learner's track) is specific, and the examples (e.g., 'scratch enrollee who's really a power operator') add clarity. It is well-distinguished from sibling tools like start_session or complete_lesson.

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 tells when to use the tool: 'Use when a learner was placed wrong.' It also provides a prerequisite: 'The learner must have started a session first,' and an authentication requirement: 'Requires admin_key.' However, it does not explicitly mention when NOT to use it or name alternatives among siblings.

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

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

No annotations are provided, so the description bears full burden. It mentions returning level, completed lessons, and next lesson, and implies state mutation ('Place or resume'), but does not disclose potential side effects, authentication needs, or error behavior. Adequate but not exhaustive.

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

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

Three concise sentences with no fluff. The critical ordering instruction 'Call FIRST' is front-loaded, and parameter guidance is efficiently integrated. 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 no output schema, the description covers return values and key parameter rules. It lacks details on error cases (e.g., unknown email, idempotency), but for a session-start tool, the essentials are present. Sufficient for most use 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?

Schema coverage is 100%, but the description adds significant value beyond schema: explains that 'learner' must be an email (stable key), that 'name' is for certificates, and that 'level' can optionally override. This aids correct parameter 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 specifies 'Call FIRST. Place or resume a learner: returns their level, completed lessons, and the recommended next lesson.' This clearly identifies the tool as an initialization step for a learner session, with specific verb and resource, and distinguishes it from siblings like 'complete_lesson' or 'course_stats'.

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

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

Explicitly states 'Call FIRST,' indicating the tool is the entry point. Provides guidance on passing email as 'learner' and using 'name' for certificate, but does not explicitly list when not to use alternative tools. Still, the ordering 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?

Despite no annotations, description fully discloses behavior: it's a write operation that routes to Slack and feedback log, non-destructive, no admin key needed. No contradictions.

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

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

Two sentences, front-loaded with purpose, followed by usage and destination. Every sentence adds value and is clearly structured.

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

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

Covers purpose, usage, behavior, and routing. With no output schema and simple parameters, description is complete and actionable for an AI agent.

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% with parameter descriptions. Description adds context like 'FOR the learner' and maps 'kind' options to feedback types, but does not significantly exceed schema information.

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?

Explicitly states the tool sends feedback to the course team on behalf of the learner, listing specific types (confusing, bug, idea, praise). Distinguishes from sibling tools which focus on lessons and sessions.

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 when-to-use guidance: when a learner is stuck or reacts, and always at session wrap. Also clarifies what it is not for ('No grade, no admin key').

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

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

No annotations are provided, so the description carries full responsibility. It discloses the one-way nature of the redeem parameter ('one-way'), the requirement for admin_key, and the return information (who earned it, reward, when, redeemed status). No contradictions.

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

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

The description is a single, dense sentence that efficiently conveys purpose, usage, and key details. It is front-loaded with the operator context. Could be slightly more structured, but remains concise and clear.

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 no output schema, the description fully covers expected return data (who, reward, when, redeemed status) and authentication requirement. For a simple tool with 3 parameters, this is complete and 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 coverage is 100% with adequate descriptions. The description adds context for the admin_key ('Worker secret ADMIN_KEY') and reinforces the redeem behavior, but does not significantly extend 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?

Description uses specific verb 'validate' and resource 'reward code', clearly indicating the action. It distinguishes from sibling tools (all lesson/course-related) by specifying the context (Capital Factory gift shop) and the code formats (GT- or FG-).

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

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

Description identifies the target user ('OPERATOR') and the context (gift shop), implying when to use. It does not explicitly state when not to use, but sibling tools are unrelated, so no alternatives are needed. A clear usage context is provided.

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