Moltline Educator Toolkit

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

Annotations already declare read-only, idempotent, non-destructive, but the description adds context annotations cannot: no plan is required, exactly one skill is returned, and malformed input never raises a protocol error but returns a structured {"error": ...} object with remediation. It also states retry is always safe after correcting input.

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

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

Front-loaded with the free-gateway purpose, then the example, then the sibling exclusion and error contract. The inline input/output JSON illustration is somewhat verbose given an output schema exists, but each sentence still carries routing or error-handling 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?

Covers prerequisites (no plan), selection behavior (automatic from slug), exclusion to get_full_skill, and a full error contract with remediation. An output schema exists, so the return-shape detail is redundant but harmless, and nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents slug, but the description adds a worked example ({"slug": "curriculum-architect-hs"}) and clarifies that the slug determines which skill is selected automatically. That is meaningful added meaning beyond the schema, though limited to a single parameter.

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

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

States a specific verb and resource ('Load a product's free gateway skill with its complete instructions') and immediately scopes it with 'FREE' and 'chosen automatically from the slug'. It explicitly distinguishes itself from the sibling get_full_skill, so an agent can route without opening either schema.

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

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

Gives an explicit positive trigger ('Use when the caller wants usable instructions immediately') and an explicit negative one ('Not for the product's other skills: those are named and need get_full_skill with a skill_name, which requires a paid plan'). It even names the corrective path for bad input ('Use list_products').

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?

Adds context annotations cannot express: the PREMIUM license requirement, and a concrete error contract (no protocol error is raised; returns {"error": ...} with fix guidance), plus retry-safety after correcting input. It repeats the read-only/idempotent claims already carried by annotations, which costs it a point, but the error and licensing disclosure is genuine added value.

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-loads the purpose and routing exclusions, which is the right ordering, but the sentence "Returns persona plus every skill for one product" restates the opening line almost verbatim, and the full example return object is largely redundant given a declared output schema.

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

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

For a single-parameter read tool with annotations and an output schema, everything an agent needs is present: scope, alternatives, license gate, error behavior, and retry semantics. No gaps remain that would cause a mis-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 coverage is 100% and the slug property is already documented, so the baseline is 3; the description adds a concrete worked input ({"slug": "curriculum-architect-hs"}) and ties invalid slugs to the returned error shape, which reinforces expected format 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 ("Load one product in full: its persona plus every paid skill") and immediately names what it is not for at the sibling level. The distinction from get_full_skill, get_free_skill and list_products is explicit, so an agent can choose without opening schemas.

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

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

Gives a positive condition ("Use when the caller wants the whole product") and two explicit exclusions with the alternatives named: single skill goes to get_full_skill, free look goes to list_products/get_free_skill. That is the full when/when-not/alternative triad.

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, idempotentHint and destructiveHint=false, yet the description still adds real value: the PREMIUM/license gating requirement, and a non-obvious error contract (no protocol errors, returns {"error": ...} with a fix hint, safe to retry after correction). It does redundantly restate read-only/idempotent and leaves 'PREMIUM (license)' undefined, so it stops short of 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?

Front-loaded with purpose, then example, then selection rule, then exclusions and error behavior — a sensible ordering. The inline JSON example of input and output is somewhat verbose given the schema and output schema already encode both shapes.

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

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

An output schema exists, so return values need no prose, and the description nonetheless covers selection, exclusions, license gating and error recovery. Nothing an agent needs to invoke this two-param read tool correctly is missing.

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

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

Schema coverage is 100% and both params already carry examples, so the baseline is 3. The description adds the relationship between the two params (one skill selected by skill_name within a product slug) and a worked input/output pair, which clarifies selection semantics slightly 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 ('Load one paid skill's complete instructions from a product') and explicitly bounds scope to a single named skill. It names both siblings it is not (get_free_skill, get_full_product), so an agent can select it without opening any schema.

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

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

Gives an explicit positive trigger ('Use when the caller wants one specific paid skill') plus two explicit exclusions with the tool to use instead for each case. This is textbook when/when-not/alternatives 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, idempotentHint, and destructiveHint=false, so the safety profile is partly redundant here. The description still adds real value with its error contract: it never raises a protocol error, returns {"error": "..."} with remediation hints, and is safe to retry after correction. Only the repeated read-only/idempotent claim duplicates structured data.

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 purpose and cost ("FREE") are front-loaded, then outputs, then an example, then exclusions and error behavior. The inline JSON example is long but earns its place by illustrating both input and return shape; a tighter description could trim some of it.

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

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

For a two-parameter read-only computation with an output schema already present, this covers everything: what it computes, example input/output, when not to use it, and exactly how failures surface. An agent could call it correctly on the first attempt.

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%, so baseline is 3. The description goes beyond the schema by showing a concrete call with {"scores": [...], "max_score": 100} and the resulting payload, which clarifies how max_score scales the percentage bands and what the scores array represents in practice.

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 ("summarize") and resource (an assessment's scores), then enumerates the exact outputs produced: mean, median, std dev, quartiles, bands, outliers. It explicitly separates itself from readability_report, so an agent can pick it without opening either schema.

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

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

"Use on a list of scores already earned" gives the positive condition, and "Not for the readability of the assessment itself (readability_report)" gives the exclusion plus the named alternative. Nothing is left to inference about when to select this tool over a sibling.

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 cover read-only, idempotent, non-destructive and closed-world, but the description adds a genuinely new contract: it never raises a protocol error and instead returns an {"error": ...} object with a fix hint, which tells the agent how to recover. It does restate read-only/idempotent, which is redundant with the annotations, keeping it out of the top band.

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?

Purpose is front-loaded in the first sentence and the usage/exclusion guidance follows logically. The inline input and output JSON examples are large and partly duplicate the schema, which costs some tightness but still earns its place as illustration.

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 trigger, exclusions, error behavior, retry safety and a sample output despite an output schema already existing. For a two-parameter read-only tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: which segments get more or less time, and a worked example mapping ['Warm-up','Direct instruction','Practice','Exit ticket'] to concrete durations. That clarifies how the segment list is interpreted beyond the schema's name-only 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?

Uses a specific verb+resource ('Split a class period into timed segments') and states the weighting behavior, so the agent knows exactly what it produces. It also names the cases it does not cover (multi-day planning, spaced review), separating it from adjacent planning 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?

Gives an explicit trigger ('Use when one fixed class period must be divided into segments') plus exclusions and the sibling that handles the excluded case (spaced_repetition_plan). No inference needed to choose this tool over 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, idempotentHint, non-destructive and closed-world, and the description still adds non-obvious traits: it is FREE, it returns metadata only with no persona text or skill instructions, and it never raises a protocol error but returns {"error": ...} — with a retry-safety statement. That is genuine context beyond the structured 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?

Front-loaded with purpose, then usage boundaries, then error behavior — good ordering with no filler sentences. The inline example of the returned object partly duplicates the output schema and makes the description longer than strictly needed.

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 an output schema existing, the description covers everything an agent needs: what the list contains, downstream slug usage, what is deliberately absent (persona text, skill instructions), and error/retry 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?

Zero parameters, so the baseline is 4. The description confirms 'Takes no arguments' and shows a typical {} call, but this only restates what the empty schema already shows.

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 with scope: 'List the 8 educator products with their included skills.' It also explicitly distinguishes itself from catalog search and from get_free_skill, so an agent can pick it without opening a schema.

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

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

Gives an explicit trigger ('Use when the caller wants to see what this server covers') and two named exclusions with the tools that replace it (search_catalog for keyword search, get_free_skill for actionable instructions). It also routes the caller forward: use returned slug values with get_free_skill, get_full_product, or get_full_skill.

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, idempotentHint, and destructiveHint=false, so restating 'read-only and idempotent' adds little. The genuinely new content is the error contract: no protocol errors, a structured {"error": ...} payload with examples, and the guarantee that retry after correction is safe — that is behavior an agent cannot infer from 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?

The opening sentence and the usage/exclusion sentences are front-loaded and efficient, but the block of pretty-printed sample output duplicates what the output schema already provides (has_output_schema=true), and the error guidance is buried at the end after that 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?

With an output schema and full annotations present, the description covers everything still needed: scope, alternatives, error behavior, and retry safety. Nothing an agent requires to invoke this 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 the schema already explains both text and target_grade, including the 0-default skip behavior. The description's example input and the 'gap' field in the sample return reinforce but do not extend the schema's semantics, so 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?

Names a specific verb+resource (Flesch-Kincaid readability analysis of teaching text) and enumerates the metrics produced. It explicitly distinguishes itself from grade_curve and from the creator server's analyze_writing, so an agent can route without opening a schema.

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

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

States the positive case ('Use on teaching text where the reading level matters') and two explicit exclusions with the named alternative for each (grade_curve for student scores, analyze_writing for general prose). This is the when/when-not/alternatives pattern at full strength.

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