delegation-school

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

Since no annotations are provided, the description carries the full burden. It discloses the core behavior (recording and advancing/reteach) and the importance of reflection. However, it omits details about side effects, idempotency, or error conditions, leaving gaps for an agent.

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

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

The description is extremely concise: two sentences that front-load the main purpose and immediately clarify the critical parameter behavior. Every sentence adds value, and there is no wasted text.

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

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

Given the absence of an output schema and annotations, the description could do more to cover prerequisites (e.g., session existence), error handling, and return value expectations. It adequately covers input and main behavior but lacks completeness for a fully autonomous 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%, and the description largely reiterates parameter descriptions from the schema. While it adds context for 'reflection' (character limit and purpose), it does not provide significant new meaning beyond what the schema already conveys.

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 function: recording a lesson result after grading. It explains the effect of the 'passed' parameter and distinguishes from general feedback tools like submit_feedback. However, it does not explicitly differentiate from all sibling tools, such as 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 implies when to use the tool with 'AFTER grading', but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among the sibling tools. The usage context is only implied.

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

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

With no annotations, the description carries full burden. It discloses the tool is read-only ('inspectable state'), requires admin_key, and returns a snapshot. It does not mention rate limits or data freshness but is sufficiently transparent for a simple read operation.

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

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

The description is extremely concise (one sentence plus a fragment), front-loaded with purpose, and every word adds value. No wasted text.

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

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

Given the tool's simplicity (one parameter, no output schema, no nested objects), the description fully covers what the tool returns and its purpose. It mentions specific output fields and the intended use case, making it 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% (one parameter admin_key described). The description adds that admin_key is required and is the 'Worker secret ADMIN_KEY', but this largely mirrors the schema. Baseline 3 is appropriate as the description adds minimal extra meaning.

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

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

The description clearly states the tool provides a 'usage snapshot of the whole course' with specific data points (learner count, level mix, completions, etc.). It uses specific verbs and distinguishes itself from siblings like 'overview' by targeting an operator agent and listing unique metrics.

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

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

The description explicitly says it answers 'what is the state of the work?' for an operator agent and requires admin_key, implying admin-only use. It provides clear context but does not mention when not to use this tool or compare it to alternatives like 'overview'.

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

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

No annotations are provided, so the description must disclose behavioral traits. It only mentions that the output is 'full markdown' but does not state side effects (none expected), idempotency, authentication needs, or error scenarios like invalid slug. The teaching advice ('Teach from it...') is irrelevant to tool behavior.

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

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

The description is two sentences long. The first sentence is efficient and clearly states the function. The second sentence adds instructional context (how to use the lesson during teaching) which may not be essential for tool selection but does not significantly detract. Could be trimmed, but overall concise.

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 tool with one parameter and no output schema, the description is minimally adequate: it explains what the tool does and where the slug comes from. However, it does not describe the return format beyond 'full markdown' (e.g., whether it's plain text or includes metadata), nor mention any error handling. The teaching advice adds operational context but not completeness.

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

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

Schema description coverage is 100% (the single parameter 'slug' is described as 'Lesson slug from list_lessons / start_session'). The tool description does not add any new information beyond what the schema provides, so the baseline score 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?

The description clearly states the tool retrieves the full markdown of a lesson by slug. The verb 'Get' and object 'full markdown of one lesson' are specific and unambiguous, distinguishing it from sibling tools like list_lessons (listing) or start_session (starting a session).

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 after obtaining a slug from list_lessons or start_session (as noted in the input schema). However, it does not explicitly state when to use this tool versus alternatives, nor provides any exclusions or conditional guidance. No sibling comparisons.

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 responsibility for behavioral disclosure. It does not mention side effects, authentication needs, rate limits, pagination, or ordering, leaving the agent without critical context about the tool's behavior beyond the listed fields.

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, concise sentence that front-loads the key information (action, resource, return fields) and includes the optional filter. No extraneous text.

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

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

Given the tool's simplicity (one optional parameter, no output schema, straightforward listing), the description is nearly complete. It would benefit from mentioning ordering or what happens with an invalid track, but these are minor omissions.

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% (one parameter: track). The description adds 'optionally filtered to one track,' which mirrors the schema's description. With full schema coverage, a baseline of 3 is appropriate as the description provides no additional insight 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 uses a specific verb ('List') and resource ('lessons'), enumerates the returned fields (slug, title, track, order, summary), and distinguishes from sibling tools like get_lesson which retrieves a single 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 clearly states that the tool lists all lessons or optionally filtered to one track. While it doesn't explicitly mention when not to use it or alternatives, the sibling tool get_lesson provides implicit guidance for single-lesson retrieval.

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

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

The description makes it clear that this tool is informational (background reading) and not destructive. Without annotations, it effectively communicates the read-only behavior.

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

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

The description is concise with two sentences: the first states the purpose, the second clarifies the context. 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?

Given there are no parameters or output schema, the description fully covers the needed context for an overview tool.

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

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

The tool has no parameters, and the schema coverage is 100%. The description does not need to add parameter info, so it meets the baseline for zero parameters.

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

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

The description explicitly states what the tool provides: an overview of delegation.school, its three tracks, and how to run the course as a tutor. It clearly distinguishes from siblings like complete_lesson and 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?

The phrase 'Background reading' implies use for getting context before action, but there is no explicit guidance on when not to use it or alternatives. However, given its static reference nature, this is adequate.

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

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

No annotations provided, but description discloses that the change 'routes through the learner's record so the change sticks', indicating persistence. Mentions auth requirement and precondition. Lacks detail on side effects like idempotency but is still strong.

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?

Four sentences, each serving a purpose: purpose, effect, usage scenario, requirements. No unnecessary words. Well-structured and efficient.

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

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

Covers preconditions, auth, and use case. Lacks description of return value, but given no output schema, it's a minor gap. Overall complete for a simple mutation tool.

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

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

Schema coverage is 100% with descriptions for each parameter. Description adds value by clarifying the learner field should match start_session key, and admin_key is the 'Worker secret ADMIN_KEY'. Adds context 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?

The description clearly states the tool's purpose: 'reclassify an existing learner's track' with specific level values (scratch, intermediate, power). It distinguishes from siblings (e.g., start_session, complete_lesson) by focusing on reclassification.

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

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

Explicitly states when to use: 'Use when a learner was placed wrong' with an example. Also specifies prerequisites (learner must have started a session) and required admin_key. Provides clear 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?

Describes return values (level, lessons, next lesson) and the key uniqueness issue. Without annotations, it carries the transparency burden well, though could mention if it creates/updates records.

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

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

Front-loaded with 'Call FIRST', two sentences, no wasted words. Every sentence provides actionable guidance.

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

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

Given low complexity, full schema coverage, and no output schema, the description adequately covers what the tool does, how to use it, and what it returns. No gaps.

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

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

Schema coverage is 100%, and description adds meaningful context: why email is essential, name for certificate, level as optional override. Adds value beyond schema.

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

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

The description clearly states the tool is the first call to place or resume a learner, returning level, completed lessons, and recommended next lesson. It distinguishes from siblings by establishing itself as the entry point.

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 'Call FIRST' and provides detailed guidance on using email instead of name. Lacks explicit exclusion criteria for when not to use, but the context 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 given, so description carries full burden. It discloses the action (send), categories, routing to Slack+log, and constraints (no grade, no admin key). Missing minor aspects like authentication needs or whether feedback can be updated, but overall sufficient for safe use.

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?

4 sentences, no waste. Front-loaded with purpose, then when to use, then routing. Every sentence adds value. Ideal length.

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

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

Given the tool's simplicity (submit text with optional metadata), description covers all needed context: purpose, usage triggers, behavior, routing. No output schema needed; agent can correctly invoke based on description + 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 coverage 100%, so baseline 3. Description adds contextual why (feedback categories, learner follow-up) but doesn't elaborate on individual parameter semantics beyond what schema provides. 'message' is required with char limit; described in both. No extra depth.

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 sends feedback to course team for the learner, enumerates feedback types (confusing, bug, idea, praise), and distinguishes from other tools by specifying 'No grade, no admin key.' The verb 'submit_feedback' is backed by concrete scenarios.

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

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

Explicitly says when to use: when learner is stuck or reacts, and always at session wrap. Also states when not to use: for grades or admin keys. Provides alternative routing info (Slack + feedback log), making it easy for agent to decide.

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

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

With no annotations, the description carries full burden. It discloses auth requirement (admin_key), one-way redeem action, and return info (who earned it, reward, when, redeemed status). Lacks error handling details but covers key behaviors.

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', no wasted words. All information is essential and well-structured.

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

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

No output schema, so description explains return values (who, reward, when, redeemed). Covers both code types and redeem action. Missing error scenarios but complete for typical use.

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

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

Schema coverage is 100%, baseline 3. Description adds context: code format (GT- or FG-), redeem as one-way, admin_key as secret. This enriches understanding beyond schema descriptions.

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

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

The description clearly states the verb 'validate' and 'redeem', the resource 'reward code', and the operator context. It distinguishes from sibling tools which are all lesson/course related, so no confusion.

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 when to use (operator validating a reward code) and mentions the redeem option. No explicit when-not or alternatives, but sibling tools are unrelated, and context is clear.

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