Moltline Personal Suite

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds a full error contract: failures never raise protocol errors and instead return {"error": ...} with a concrete example, plus explicit retry safety. It also discloses the default 50/30/20 behavior and the exact shape of a typical response, which annotations cannot convey.

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 defaults, example output, usage guidance, and error behavior in a compact block. Every sentence carries information, though the literal JSON example and the 'FREE' marker are slightly bulky for the value they add.

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 explanation, yet the description still previews the response shape. Usage, alternatives, defaults, error handling, and retry safety are all covered for a simple four-parameter read-only 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%, so the baseline is 3; the description adds meaning by framing the three percentage parameters as the 50/30/20 default that is 'fully customizable' and showing a concrete input-to-output example. It still doesn't restate the sum-to-100 constraint in the description, leaving that to 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 ('Split monthly income into needs/wants/savings buckets with weekly equivalents') and names the sibling it is not for (savings_goal). An agent can distinguish it from tip_split and savings_goal 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 monthly income needs allocating across buckets') and an explicit exclusion with the alternative named ('Not for how long a target takes to reach (savings_goal)'). No inference required.

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 and idempotency, yet the description still adds real behavioral detail: per-event error entries instead of whole-call failure, no protocol errors ever raised, a structured {"error": ...} shape, and retry safety after correction. It also notes the 30-event cap is silently applied, which is important since excess input is dropped rather than rejected.

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 and sorting rule are front-loaded, then usage, then error and retry semantics — a sensible ordering. The "FREE." line is marketing noise and the inline example output is somewhat padded, but the sentences otherwise carry information.

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

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

For a single-param, nested-object tool with an output schema and full annotation coverage, this description covers purpose, alternatives, error mode, retry safety, and input shape. Nothing an agent needs to invoke it correctly or recover from failure 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 earns extra credit by showing a concrete input payload and by disclosing that a malformed date degrades to a per-event error rather than invalidating the mapping. That error-granularity detail is a semantic the schema does not convey.

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?

"Count the days until each named event, soonest first" gives a specific verb, resource, and output ordering in one clause. It also explicitly disambiguates from two named siblings (business_days, spaced_repetition_plan), so an agent can pick it without opening the 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 to rank named dates by how soon they arrive" states the selecting condition, and the following sentence names both alternatives with the conditions that route away from this tool. Explicit when-to-use and when-not-to-use are both present.

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?

Beyond the annotations, the description adds meaningful behavior: it returns exactly one automatically chosen gateway skill, it is free and requires no plan, and invalid input yields a structured {'error': ...} response rather than a protocol error. It also explicitly says calls are read-only and idempotent, making retry safety clear.

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 definition is front-loaded with purpose and usage, then moves to examples and error behavior. It is somewhat long for a one-parameter tool, but nearly every sentence contributes routing, return-shape, or retry 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?

Given the simple one-parameter schema and the existence of an output schema, the description is more than complete. It covers routing to get_full_skill, free access, return shape, error behavior, and retry safety, so an agent has everything needed to invoke it 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 the slug parameter is already documented. The description still adds value by showing a typical input, explaining that the skill is chosen automatically from the slug, and giving an error example that routes unknown slugs to list_products.

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

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

The description states a specific verb and resource: 'Load a product's free gateway skill with its complete instructions.' It explicitly distinguishes this from the product's other skills, which require get_full_skill, so an agent can route correctly without opening sibling 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?

It gives an explicit use case ('Use when the caller wants usable instructions immediately') and an explicit exclusion plus alternative ('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 clarifies that no plan is required for 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description goes further: it discloses the non-throwing error contract ({"error": ...} with a cause-and-fix message), the retry-safety implication, and the PREMIUM license gating. Minor gap: it does not say whether an unlicensed caller gets a distinct error shape versus an unknown slug.

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 core purpose and well-ordered (what it does, example, when to use, when not, error contract). One redundant sentence — "Returns persona plus every skill for one product" restates the opening, and the return-shape example duplicates the 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-param read tool with a full output schema and rich annotations, this leaves nothing an agent needs missing: purpose, alternative routing, license caveat, error semantics, and retry safety are all present.

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 earns extra by showing a concrete call ({"slug": "inbox-assistant"}) and the specific failure message for a bad slug (unknown slug '<value>'), which tells the agent the identifier must match list_products output exactly.

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?

"Load one product in full: its persona plus every paid skill" names a specific verb, resource, and the exact payload returned. It is immediately distinguishable from get_full_skill (one skill), get_free_skill (free tier), and list_products (enumeration).

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 selection condition ("Use when the caller wants the whole product") and names the two exclusions with the alternatives that cover them: get_full_skill for a single skill and list_products / get_free_skill for a free look. Nothing is left to inference.

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

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

Beyond the annotations (readOnly/idempotent/non-destructive), it discloses the error contract in detail: no protocol errors are raised, failures come back as {"error": ...} with a fix hint, and retrying after correction is safe. It also flags the PREMIUM/license gating, which the annotations do not convey and which materially affects whether a call will succeed.

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 core purpose and the usage decision, and most sentences carry distinct information (alternatives, error contract, retry safety). The inline request/response example is partly redundant with the existing output schema, adding a little length without new semantics.

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, chaining (slug comes from list_products, skill_name from its skills array), sibling routing, license gating, and failure/retry behavior. With an output schema present, the return-value explanation is a bonus rather than a gap, so an agent has everything needed to call it 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 the baseline is 3, but the description adds a concrete worked example ({"slug": "inbox-assistant", "skill_name": "Zero Sweep"}) that shows the expected value shape and the product-plus-skill pairing. It stops short of saying how skill_name matching behaves on near-misses, so not a 5.

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 immediately scopes it to exactly one named skill. It explicitly distinguishes itself from get_free_skill and get_full_product, so an agent can pick correctly 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 an explicit when-to-use ('Use when the caller wants one specific paid skill') plus two named exclusions with their alternatives: the free gateway skill goes to get_free_skill, and the full set goes to get_full_product. Nothing is left to inference.

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

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

Beyond the readOnly/idempotent annotations it discloses content boundaries ('metadata only - no persona text and no skill instructions'), cost ('FREE'), and a non-standard error contract: no protocol errors, instead an {'error': ...} object, plus that retry after correction is safe. That is behavior an agent cannot infer from annotations alone.

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 verb, scope, and a sample return object, then usage and exclusions. Slightly longer than needed: the return-shape example duplicates the output schema, and the read-only/idempotent/retry sentence restates annotation content.

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, yet the description still sketches the object shape and explicitly flags what is absent (persona text, skill instructions), which is exactly the distinction an agent needs before chaining to get_free_skill. Error semantics and sibling routing are both covered.

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 schema has nothing to explain; the description confirms 'Takes no arguments,' which closes the loop. No further parameter meaning is needed, though it also spends words on the empty argument list.

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

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

States a specific verb and resource ('List every product in the Personal Suite line with its included skills') and bounds the scope to 20 products. It explicitly carves itself out from catalog-wide keyword search and from instruction-fetching tools, so an agent can pick it over siblings 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 a positive trigger ('Use when the caller wants to see what this server covers'), explicit exclusions ('Not for keyword search across the whole 138-product catalog... search_catalog does, and not for instructions... get_free_skill'), and names the downstream tools that consume the returned slugs.

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 readOnly/idempotent/non-destructive, and the description adds value beyond them: it discloses the error contract (returns {"error": ...} rather than raising a protocol error, with a sample message), asserts retry safety after correction, and flags it as administrative math rather than advice. This is exactly the context annotations cannot express.

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?

Well front-loaded — the one-line purpose and FREE badge come first, then the example, then usage and error behavior. The example return value is largely redundant given an output schema exists, which is the only real slack in an otherwise tight definition.

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 3-param pure-computation tool with full schema coverage, annotations, and an output schema, the description covers everything left: when to use, what it is not, compounding behavior, and the error/retry contract. An agent can call it correctly from this alone.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by giving a worked example ({target: 10000, monthly_saving: 400, annual_rate_pct: 4}) and stating that interest compounds monthly, showing how the parameters interact rather than just restating their definitions.

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

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

States a specific verb+resource+scope: 'Compute months to reach a savings target at a monthly contribution', and immediately disambiguates from budget_split and loan_payment. The concrete example input/output makes the computation unambiguous without opening the 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?

Explicitly states when to use ('when a target amount and a monthly contribution are known') and names two exclusions with the sibling responsible for each (budget_split, loan_payment). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered structurally. The description adds genuinely new behavior beyond that: it never raises protocol errors and instead returns {"error": "<what is wrong and how to fix it>"} with a concrete example, which materially changes how an agent should handle failure and retry. Its final sentence restating read-only/idempotent is redundant with the annotations, so it falls just 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?

Purpose is front-loaded in the first line, followed by interval rules, an example, usage guidance, and error semantics in a logical order with no filler sentences. The inline JSON example is slightly long and partially duplicates the available output schema, which is the only reason it is not a 5.

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

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

For a two-parameter read-only computation with an output schema already present, the description covers everything an agent needs: what it computes, the interval formula, input/output shape, sibling disambiguation, and non-throwing error contract with retry safety. Nothing required 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 description coverage is 100%, so both start_date and sessions are already documented, and the baseline would be 3. The description adds value beyond the schema by working through a concrete call ('{start_date: 2026-09-01, sessions: 4}' returns start plus a reviews array with session, day_offset, date), which clarifies how inputs map to the expanding-interval output rather than just restating field names.

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 ('Build a spaced-repetition review schedule') and immediately pins down the defining behavior: expanding intervals of 1, 3, 7, 14, 30, 60, 120, 240 days. It explicitly names the sibling it is not (lesson_timer for a single session), so an agent can disambiguate 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 positive trigger ('Use when material must be reviewed on expanding intervals') and an explicit exclusion with the named alternative ('Not for timing a single session, which the educator server's lesson_timer handles'). Both the when and the when-not are stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the restatement of read-only and idempotent is largely redundant. However, the description adds genuinely new behavior: the tool never raises a protocol error and instead returns an {"error": ...} payload, plus the retry guidance. That error contract is the valuable addition beyond 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?

Front-loaded with purpose and a worked example, then usage, then errors — a sensible order. The error paragraph is somewhat long-winded (repeats the error example twice conceptually), and "FREE." is promotional filler, but nothing is confusing.

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 and the description still sketches the return shape and the error shape, covering the two possible response modes. For a three-parameter, single-purpose calculator, an agent has everything needed to call it and interpret failures.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above baseline by showing a concrete parameter->output mapping (bill 86.40, tip_pct 20, people 4 -> tip 17.28, per_person 25.92), which clarifies units and rounding intent. Constraint details (bill>0, people>=1) are repeated from the schema rather than added.

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?

Opens with a specific verb+resource: "Compute the tip and per-person split for a bill," and the example input/output makes the exact computation unambiguous. It also names the sibling it is not for (budget_split), 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?

Explicitly scopes usage ("one bill shared among a group") and provides an exclusion with the alternative named: "Not for recurring household budgeting (budget_split)." That is the when/when-not/alternative triad complete.

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