Moltline Research Desk

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

Beyond the annotations, which already declare read-only and idempotent behavior, the description discloses important behavioral traits: normal approximation is unreliable on very small or heavily skewed samples, and invalid input returns a structured error object rather than a protocol error. It also notes retry safety after correcting input, adding practical context.

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 front-loaded with the core purpose and is generally efficient, with useful example input/output and caveats. However, it includes minor non-essential elements such as 'FREE.' and repeats read-only/idempotent facts already captured by annotations.

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, an output schema exists, and the description covers usage scope, statistical limitations, exclusions, error behavior, and retry safety. An agent has enough information to call the tool correctly and understand when not to use it.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters and their constraints. The description provides an example input and repeats constraints, but does not add parameter semantics beyond what the schema already states; 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 gives a specific verb and resource: compute a confidence interval for a mean using normal approximation. It also scopes the tool precisely by excluding proportions and two-group comparisons, making it distinguishable from alternatives like ab_test.

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 states when to use the tool ('Use on data already collected, for a mean') and when not to use it ('Not for proportions or two-group comparisons'), naming ab_test as the alternative for two-group comparisons. This leaves little ambiguity for an agent choosing between 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?

Annotations already declare read-only, idempotent, non-destructive and closed-world, and the description partly restates that. The genuinely additive content is the error contract: invalid input never raises a protocol error but returns {"error": ...} with a fix hint, plus the explicit safe-to-retry guarantee. Return-shape detail is unnecessary given the output schema exists.

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 usage boundary, then error behavior — a sensible order. The lone 'FREE.' fragment is marketing noise that earns no place, but the rest is dense and useful.

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 annotations covering safety, an output schema covering return values, and full schema coverage on parameters, the description closes the remaining gaps: when to use versus not, and how failures are surfaced. An agent has everything needed to call it correctly and recover from bad input.

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 schema already documents all eight parameters, including the 'Last, First' author format and style casing. The worked input/output example reinforces composition but largely restates what the schema says, 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?

States a specific verb and resource (format a citation) and names the three supported styles (APA 7, MLA 9, Chicago author-date). It also distinguishes the tool from siblings by declaring what it does not do: find or verify a source.

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?

Explicit routing: "Use when the source details are already known and only the formatting is missing. Not for finding or verifying a source." Both the positive condition and the exclusion 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, and destructiveHint=false, but the description goes further: it explains that errors never surface as protocol errors but as {"error": ...} objects with a fix hint, and that retry after correction is always safe. That error-contract detail is exactly the kind of behavior 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?

Purpose and the "FREE" qualifier are front-loaded, and the alternative-tool routing follows immediately. The middle sentence restates the single-skill selection already implied, which is mild redundancy but the structure stays scannable.

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 one-parameter read tool with an output schema, the description still covers return shape, error contract, plan prerequisites, and sibling routing. Nothing an agent needs to call 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% and the slug parameter is already documented, so the baseline would be 3; the description earns extra credit by pairing a concrete input example with its output shape and by reinforcing where the slug comes from (list_products). It stops short of 5 because no additional slug-format edge cases are given.

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 explicitly distinguishes itself from get_full_skill, which serves the product's other skills. An agent can pick the right tool 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?

Names the selection condition ("Use when the caller wants usable instructions immediately") and the exclusion ("Not for the product's other skills: those are named and need get_full_skill with a skill_name, which requires a paid plan"). Both the when and the when-not are explicit, plus the prerequisite difference (no plan vs. paid plan).

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 non-destructiveness, but the description adds genuinely new context: the PREMIUM license requirement, the non-raising error contract that returns {"error": ...} instead of a protocol error, and the explicit retry safety after correcting input. That is exactly the kind of operational detail 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?

Front-loaded with the one-line purpose, then example, routing, and error contract in a logical order. Slightly redundant: 'Returns persona plus every skill for one product' restates the opening sentence and could be cut, but the rest of the text earns its space.

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?

Single-parameter, read-only tool with an output schema, so the return shape is already structured elsewhere; the description nonetheless sketches the response and covers the one real risk (bad slug) with a recovery path. Nothing an agent needs to call 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 coverage is 100% and the schema already carries the 'thesis-advisor' example, so the description's input example largely repeats it. It earns above baseline by tying a failure mode to the parameter — the unknown-slug error and how to recover from it — which helps an agent construct and correct the slug value.

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 explicit scope: 'Load one product in full: its persona plus every paid skill.' The scope phrase 'persona plus every paid skill' distinguishes it from get_full_skill and get_free_skill without requiring the agent to open 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 when: 'Use when the caller wants the whole product.' Then names the exclusions and their alternatives: 'Not for a single skill (get_full_skill) and not for a free look, which list_products and get_free_skill provide with no plan.' All three relevant siblings are routed.

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, but the description adds genuinely new context: a premium license requirement, an explicit error contract (never raises a protocol error, returns {"error": ...} with a fix hint), and retry safety after correction. A concrete input/output example further sets expectations for success responses.

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 action, then constraints and error behavior in a logical order. Slightly bloated by an inline JSON example and the awkward 'PREMIUM (license).' fragment, but no sentence is redundant.

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 present, the description needn't document return values, yet it still covers selection semantics, sibling routing, license gating, and error/retry behavior. An agent has everything needed to call it correctly and handle 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 coverage is 100%, so baseline is 3; the description adds marginal value with a worked example ({"slug": "thesis-advisor", "skill_name": "Outline Builder"}) and a statement that selection is by skill_name. It does not add format rules beyond the schema's 'exactly as returned by 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?

States a specific verb and resource: 'Load one paid skill's complete instructions from a product,' including the returned shape. It explicitly distinguishes itself from get_free_skill and get_full_product, so an agent can route correctly 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 when: 'Use when the caller wants one specific paid skill.' Then names both alternatives and their exclusion conditions — the free gateway skill (get_free_skill) and all skills at once (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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered; the description nonetheless adds real context: metadata-only content ('no persona text and no skill instructions'), the error envelope shape with recovery guidance, and the guarantee that malformed input never raises a protocol error. Slight redundancy in restating read-only/idempotent/retry-safety, which the annotations already imply, keeps it from 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 and cost ('FREE'), then return shape, then routing guidance, then error behavior — a sensible order. Slightly over-long: the final sentence about read-only/idempotent retry safety largely restates annotations.

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 still gives the agent the practical return shape and usage of the slug field, plus content boundaries and the error contract. Nothing an agent needs in order to call this correctly and chain it to the right follow-up tool 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?

Zero parameters, so the baseline is 4, and the description confirms 'Takes no arguments,' which matches the empty schema with additionalProperties false. Nothing further is needed.

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 Research Desk line with its included skills') and scopes it to 7 products, which is distinguishable from siblings like get_full_product and get_free_skill. The return shape example makes the output concrete without needing 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 names when to use it ('when the caller wants to see what this server covers') and names two exclusions with the alternative tools: catalog-wide keyword search belongs to search_catalog, and actionable instructions belong to get_free_skill. It also directs the agent to feed the returned slugs into 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 readOnly/idempotent/non-destructive, and the description still adds real behavioral context: no protocol errors are ever raised, failures come back as {"error": ...} with a fix hint, and retry is always safe after correction. It also discloses the statistical assumptions (p=0.5 max variance, finite-population correction), 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 the verb and purpose, followed by method, usage routing, and error semantics in a logical order. The inline example input/output pair is longer than strictly necessary for a tool with an output schema, but it is illustrative rather than repetitive.

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 three-parameter statistical calculator with an output schema, everything an agent needs is present: semantics, assumptions, error contract, idempotent retry guidance, and sibling routing. Return-value explanation is redundant given the output schema but harmless.

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 above that by giving a concrete typical input and by surfacing a constraint via the error example ('confidence_pct must be 90, 95, or 99') plus the p=0.5 assumption and finite-population-correction caveat. It stops short of explaining how population=0 interacts with the correction.

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 ('Calculate the survey sample size') and immediately scopes it to confidence level and margin. It also names the siblings it is not (stats_describe, confidence_interval), so an agent can route between them 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?

Explicit when-to-use ('Use before collecting data, to size a survey') and when-not ('Not for analyzing data already collected'), with the two competing siblings named as the alternatives. This is exactly the when/when-not/alternative structure.

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' read-only/idempotent profile, the description discloses the error contract: it never raises a protocol error and instead returns {"error": ...} with corrective guidance, plus an explicit safe-retry guarantee. That is exactly the non-obvious behavioral 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?

Front-loaded with purpose, then usage, then errors — a sensible order. However, the fully spelled-out sample output duplicates information already carried by the output schema, and the stray 'FREE.' fragment is a minor structural blemish.

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 one-parameter, read-only statistics tool with an output schema, the description covers purpose, alternatives, error handling, and retry safety. An agent has everything needed to select and 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% and the single parameter is already documented with a minItems constraint, so the baseline is 3. The concrete input example {"numbers": [12, 15, 14, 90, 13]} adds working-format intuition beyond the schema, but no extra constraint or edge-case guidance (e.g., empty arrays) is offered beyond what the schema already says.

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 ('Describe a numeric dataset') and enumerates what is produced (center, spread, quartiles, outliers). It also names the sibling tools it is not, so an agent can distinguish it from confidence_interval and sample_size 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?

'Use as a first summary of one numeric dataset' gives the positive condition, and 'Not for interval estimates (confidence_interval) and not for planning a study (sample_size)' gives explicit exclusions with named alternatives. Nothing about routing 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.