Moltline Educator Toolkit

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

Annotations already provide readOnlyHint and idempotentHint, but the description adds valuable context: it never raises a protocol error, returns an error object on invalid input with an example, and clarifies that the skill is automatically chosen. This goes beyond the annotations by detailing the error behavior and output format.

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 well-structured: starts with a clear summary, followed by an example, usage guidelines, and error handling. While it is not extremely terse, every sentence adds necessary information. It is front-loaded with the core purpose and example, making it easy to scan.

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, straightforward output), the description covers all essential aspects: input, output shape, usage context, differentiation from sibling, error handling, and safety guarantees (read-only, idempotent). The presence of an output schema further supports 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?

The input schema already covers the slug parameter with 100% description coverage, but the description adds a concrete example of typical input and output, explains the error behavior for invalid slugs, and reinforces the source of the slug (list_products). This provides extra semantic value 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 loads a product's free gateway skill with complete instructions, using the verb 'load' and specifying the resource. It distinguishes itself from the sibling 'get_full_skill' by noting that this tool is for the free gateway skill only, while other skills require a paid plan and a skill_name parameter.

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 'Use when the caller wants usable instructions immediately' and contrasts with '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 also provides error handling guidance, stating that on invalid input it returns an error object with a fix suggestion and that it's safe to retry.

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?

Description adds significant behavioral details beyond annotations: error handling (never raises protocol error, returns error object), idempotency and retry safety, premium license, and exact return structure. Annotations already provide readOnlyHint and idempotentHint, but description enriches with practical usage 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?

Description is front-loaded with purpose, includes a clear example, usage guidelines, and error handling. Every sentence is informative and earns its place. No filler or redundancy. Highly 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?

Given the tool's simplicity (one parameter, simple input, output schema exists), the description covers all essential aspects: purpose, usage, error behavior, idempotency, and license. The presence of output schema means return values are already documented. Complete for an AI agent to use correctly.

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. Description adds meaning by giving an example slug value ('curriculum-architect-hs'), specifying format (exactly as returned by list_products), and clarifying that slug must be non-empty. Also explains error handling for invalid slugs. 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 loads a full product with persona and paid skills, using a specific verb ('Load') and resource. It distinguishes from siblings by mentioning 'get_full_skill' and 'list_products' for different use cases.

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 ('caller wants the whole product') and when not to use (single skill -> get_full_skill, free look -> list_products/get_free_skill). Also mentions premium license requirement, guiding the agent on 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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explicitly stating 'Every call is read-only and idempotent', clarifying error behavior (returns error JSON, never protocol error), and asserting retry safety. No contradictions with annotations; the description reinforces and extends the structured hints.

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?

Description is well-structured: purpose first, then example, usage guidelines, error behavior, and idempotency statement. Each sentence adds distinct information. A minor length reduction could be possible (e.g., merging some sentences), but it is not verbose and front-loads key 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 tool with 2 clearly documented parameters, comprehensive annotations, and an output schema, the description covers all necessary aspects: purpose, usage boundaries, error handling, retry safety, and relationship to siblings. No gaps are apparent; the description is fully sufficient for correct tool 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 coverage is 100% with detailed descriptions for both slug and skill_name. The description provides a typical input example ('{"slug": "curriculum-architect-hs", "skill_name": "unit-planner"}') which adds illustrative value but does not introduce new semantics or constraints beyond the schema. Baseline 3 is appropriate given high schema coverage.

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 clearly states the tool loads 'one paid skill's complete instructions from a product', specifies it is premium/license-restricted, and provides an example input-output. It distinguishes itself from sibling tools get_free_skill and get_full_product by noting differences in scope and licensing. The verb 'load' and resource 'paid skill's complete instructions' are specific and unambiguous.

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 when to use ('when the caller wants one specific paid skill') and when not to use ('Not for the free gateway skill' and 'not for every skill at once'), naming the alternative tools. It also provides guidance on error handling and retry safety, covering both correct and incorrect usage scenarios.

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 provide readOnlyHint and idempotentHint. The description adds value by disclosing that the tool never raises protocol errors on invalid input, instead returning an error object with a fix suggestion. This is a behavioral trait beyond what annotations capture.

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 well-structured: purpose sentence, list of stats, example, usage guideline, and error behavior. It is informative but not overly verbose. Minor waste: the 'FREE.' appears extraneous but does not detract significantly.

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 complexity, the description covers purpose, exact statistics returned, input/output example, usage guidelines, error handling, and distinguishes from sibling. The presence of an output schema reduces the need to detail return values, but the description still provides a concrete sample. Fully 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?

The input schema has 100% description coverage, so the schema already documents the parameters well. The description provides a typical input example and output, but does not add new semantic meaning to the parameters themselves. 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 starts with 'Summarize how an assessment landed: stats, bands, and outliers,' which clearly states the verb (summarize) and resource (assessment scores). It distinguishes from the sibling 'readability_report' by explicitly noting it is not for the readability of the assessment 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?

The description explicitly states 'Use on a list of scores already earned. Not for the readability of the assessment itself (readability_report).' This provides clear when-to-use and when-not-to-use guidance, and names the alternative sibling 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?

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond by stating 'this tool never raises a protocol error — it returns {"error": ...}' and that 'Every call is read-only and idempotent, so after correcting the input it is always safe to retry.' No contradiction with 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?

Every sentence earns its place: core purpose, weighting principle, example, usage boundary, error behavior, safety note. Front-loaded with the most important information. No redundancy or fluff.

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 the tool's simplicity (2 params, simple logic), the description covers when to use, how parameters work via example, error handling, weighting strategy, and idempotent/read-only behavior. An output schema exists (signal true) and the description provides a sample output structure. An agent has everything needed to invoke the tool correctly.

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%—both parameters have descriptions. The description adds meaning by showing an example input mapping (minutes=50, segments list) and noting the weighting heuristic ('opener and closer get less time; core activities get more'). This clarifies how parameters affect results 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 opens with 'Split a class period into timed segments with sensible weighting,' which clearly states the verb, resource, and outcome. A concrete example input and output reinforces the purpose. The sibling tools are unrelated (get_free_skill, grade_curve, etc.), so no sibling differentiation is needed.

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 'Use when one fixed class period must be divided into segments. Not for multi-day planning and not for spaced review, which the personal server's spaced_repetition_plan builds.' This gives clear when-to-use and when-not-to-use guidance, and names an alternative 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?

The description goes beyond annotations by clarifying the tool returns metadata only (no persona text or skill instructions), is idempotent and read-only, and never raises protocol errors but returns a structured error object on invalid input. This adds significant context beyond the readOnlyHint, idempotentHint, and destructiveHint 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 description is well-structured, front-loading the core purpose, then providing a sample output, usage guidance, and error handling. Every sentence adds value without 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?

Given zero parameters, rich annotations, and an output schema, the description is complete. It covers purpose, output format, usage with siblings, error behavior, and idempotency. Nothing is missing for an effective agent 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?

With 0 parameters and 100% schema coverage, the description reinforces that no arguments are needed, and it explains that even 'invalid, missing, or malformed input' is handled gracefully. The description also illustrates typical output structure, though parameter semantics are inherently simple here.

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 lists the 8 educator products with included skills. It specifies the output structure and distinguishes from siblings like get_free_skill and search_catalog, making the purpose unmistakable.

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 when to use this tool (to see what the server covers) and when not to (for keyword search across the full catalog, which search_catalog does; for instructions, which get_free_skill does). It also provides a usage pattern by telling the caller to use returned slug values with other tools.

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 reinforces the annotations (readOnlyHint, idempotentHint, destructiveHint) with a statement that every call is read-only and idempotent. It also uniquely discloses error behavior: the tool never raises a protocol error but returns an error object with fix instructions. This adds significant 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?

The description is well-structured and front-loaded with the primary purpose. The example input/output is helpful but slightly lengthy; however, every sentence serves a purpose (usage guidance, error behavior, idempotency). A minor reduction in example detail could improve conciseness.

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 a moderate tool with 2 parameters and an output schema, the description covers all necessary aspects: core functionality, usage boundaries, error handling, idempotency, and a typical example. No information gaps remain.

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 description adds substantial meaning beyond the schema. It provides a concrete JSON input/output example showing how target_grade influences the gap assessment and what output fields look like. It also explains error handling for invalid input.

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 analyzes teaching text with Flesch-Kincaid readability and leveling advice. It distinguishes from sibling tools grade_curve and analyze_writing by specifying what the tool is for and what it is not for.

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 states when to use the tool ('teaching text where the reading level matters') and when not to use it ('Not for scores students earned (grade_curve) and not for general prose style, which the creator server's analyze_writing covers'). This provides clear guidance on selecting 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.