Learnosity Build Aide

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint false, openWorldHint), but the description adds genuinely useful behavior: the tool returns a message and link rather than recording anything, and the agent must not solicit data in chat. That is real context beyond the structured fields, though it says nothing about output shape (covered by the output schema).

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 triggering condition and tight throughout, with no filler. There is mild repetition between 'This does not collect feedback in the chat' and 'Do not ask the user for their email... in the chat', which could be merged into one sentence.

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 zero-parameter, read-only tool with an output schema, the description covers everything an agent needs: when to invoke it, what it produces, and the constraint against gathering data in conversation. Nothing material 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?

The tool takes no parameters, so there is no parameter meaning to add; the baseline for a zero-parameter tool applies. The description correctly implies there is nothing to supply beyond the call itself.

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 trigger (user wants to give feedback, report a problem, or suggest an improvement) and a concrete outcome (a friendly message plus a link to the Learnosity MCP Feedback Page). It also delimits scope by saying it applies to the Learnosity MCP server or its documentation, which cleanly separates it from the docs- and skills-related siblings.

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 when-to-use condition and explicit exclusions: do not collect feedback in the chat, and do not ask for email, credentials, ratings, or structured fields. An agent knows both when to call it and what not to do afterwards.

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, openWorldHint and destructiveHint=false, so safety is covered structurally. The description adds genuinely useful behavior: results are 'cached' and omitting source fans out across every configured source. It does not explain cache staleness or refresh behavior, which the word 'cached' hints at.

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?

Three short sentences, front-loaded with the action, followed by prerequisite discovery and the default-case behavior. No redundant restatement of the tool name or filler.

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, return values need no explanation, and the description covers sourcing, defaults, and the cached nature of results. The only remaining ambiguity is what 'cached' implies about freshness, which an agent may need to know for correctness-sensitive use.

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

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

Schema coverage is 0% and the single parameter has no description in the schema, so the description must carry the load. It does: it explains how to obtain valid source ids and precisely defines the null/default semantics as 'categories from every configured source'.

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 cached Learnosity categories') and makes clear this is about category listings rather than documents or sources. It is separable from siblings like read_document or search_docs_sources, though it doesn't explicitly contrast with them.

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 concrete routing guidance: use list_docs_sources or the learnosity://sources/index resource to discover valid source ids before calling. It also covers the no-argument default case. It stops short of saying when a caller should prefer this over listing documents directly.

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=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the workflow role of this call (id discovery prerequisite), which is useful context beyond the annotations, but it says nothing about ordering, size, or refresh behavior of the returned source list.

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?

Two sentences, no filler, with the purpose stated first and the prerequisite guidance second. Every clause carries information an agent needs before calling.

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 zero-param, read-only discovery tool with an output schema present and annotations covering the safety profile, the description only needs to state purpose and sequencing. Both are present, including the alternative URI access path.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to elaborate and the baseline applies. The schema already sets additionalProperties=false, so nothing further is needed 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 opens with a specific verb+resource: "List the configured Learnosity documentation sources." That clearly distinguishes it from read_document or search_docs_sources, which consume source ids rather than enumerate them. It does not explicitly contrast with the close sibling list_docs_categories, keeping it short of a 5.

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 states the usage context directly: call this "before searching or reading" to discover valid source ids, and it names an alternative (learnosity://sources/index) for the same purpose. It does not say when not to use it or how it relates to list_docs_categories, so a small gap remains.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing that the document is 'cached' (potential staleness) and that source ids must be discovered first, but it says nothing about failure behavior for invalid ids or whether the cache is ever refreshed.

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?

Two short sentences with no filler, and the core action plus required inputs are front-loaded before the discovery hint. Every clause carries 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?

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. However, with zero schema descriptions across both parameters, the definition should say more about article_id and about what happens when a cached document 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 0% for two required parameters, so the description carries the burden. It restates that both are required and explains where 'source' values come from, but gives no guidance on the expected format of 'article_id' or whether it is a numeric id, slug, or opaque key.

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 ('Read a cached Learnosity document') and names the two required inputs, so an agent can tell it apart from list/search siblings. It does not clarify the boundary with search_docs_sources, but the read-one-document framing is clear.

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?

Provides a useful prerequisite ('Use list_docs_sources or learnosity://sources/index to discover valid source ids') rather than a when-to-use rule. It never states when to choose this over search_docs_sources or what to do when an id is unknown or stale, leaving usage largely implied.

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

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

Beyond the readOnly/openWorld annotations, the description discloses two non-obvious behaviors: unfiltered search spans all configured sources by default, and hits touching lower-level APIs are withheld unless off_golden_path_reason carries a real justification. That gating rule is exactly the kind of context annotations cannot convey. It does not describe result ranking or trimming, so a 4 rather than 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?

Three sentences, each doing distinct work — scope, source-id discovery, and the withholding rule — with the most load-bearing constraint front-loaded. No filler, though the off_golden_path_reason clause is dense and slightly tangled by nesting the requirement inside the same sentence as the restriction.

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 explain return values, and annotations cover the safety profile, so the remaining burden is behavioral and parametric. The unusual gating behavior is fully explained; the gaps are limit/category_id semantics and any note on result ordering.

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 0%, so the description must carry all parameter meaning. It does well for sources (default = all configured, discoverable via a sibling) and off_golden_path_reason (required when steering off the golden path), but says nothing about limit, query, or category_id, leaving three of five parameters undefined anywhere.

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 a specific verb+resource ("Search cached Learnosity documentation sources"), which is clearly distinct from siblings like read_document and list_docs_sources. It distinguishes discovery from searching by routing source discovery to list_docs_sources, though it never explicitly contrasts against skills_search or read_document.

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 concrete prerequisites (call list_docs_sources or read learnosity://sources/index to get valid source ids) and states the default behavior when sources is omitted. It stops short of saying when to reach for read_document or skills_search instead, so the alternative-selection guidance is incomplete.

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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is conveyed by structured fields. The description adds only an enumeration of returned fields, which the output schema already covers, and says nothing about result volume, pagination, or how the optional apis filter narrows the set.

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?

A single front-loaded sentence with no filler or redundancy. Brevity costs it here, since the space saved went toward under-specification rather than efficiency, but the sentence itself is clean and well-ordered.

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 not be explained, but an unfiltered list tool with a default limit of 200 and an undocumented apis filter leaves the agent unable to reason about scope or pagination. Nothing routes it against skills_search or skills_read, which is essential given three overlapping skill tools.

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 0% for two parameters, so the description is the only possible source of meaning, and it provides none: "APIs" appears to describe a returned field rather than the apis filter argument and says nothing about limit's default of 200. This is a genuine gap, but the description's field enumeration indirectly tells the agent what the apis filter ranges over, keeping it from a bottom score.

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 clear verb + resource ("List Learnosity integration skills") and names the returned fields (ids, titles, goals, APIs), so an agent knows exactly what the tool produces. It falls short of a 5 because it never distinguishes the tool from its siblings skills_search and skills_read, which sound like competing ways to reach the same skill data.

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?

There is no guidance on when to use this tool versus skills_search or skills_read, despite both being listed siblings operating on the same resource. The description also doesn't say when a listing is preferable to a targeted lookup or search, or what happens if the result set is large.

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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully discloses the return format (Markdown body), but says nothing about the max_bytes cap or what happens when content exceeds it — a real behavioral gap for a read tool.

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?

A single front-loaded sentence with the resource, lookup key, and return type; no filler or 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?

An output schema exists, so return-value detail is not required, and the Markdown body note is a helpful addition. However, for a tool exposing a size-limiting parameter, the absence of any truncation/limits discussion leaves an agent unable to predict large-skill behavior.

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 0% for two parameters. skill_id is self-evident, but max_bytes (default 200000) is never explained in the description — no mention of truncation, byte counting, or whether a truncated result is signaled. With no schema documentation, the description should compensate and does not.

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 ('Read one Learnosity integration skill by id') and adds the return artifact ('its Markdown body'). The singular 'one ... by id' framing implicitly separates it from skills_list and skills_search, though those siblings are never named.

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?

Usage is only implied: reading a single skill requires an id, which suggests a prior list/search call, but the description never states when to prefer this over skills_search or skills_list, nor any prerequisites. Adequate but with clear gaps.

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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful information by disclosing which fields are indexed for matching, but says nothing about ranking, empty-result behavior, or match semantics.

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?

A single tight sentence with the searchable-field list front-loaded after the verb-resource pair. Nothing is redundant, though the field enumeration could be structured more scannably.

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?

The output schema exists, so return values needn't be described. However, for a search tool the description omits match semantics, result ordering, and pagination behavior beyond the limit parameter, leaving gaps an agent would want when composing queries.

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 0%, so the description carries the burden for two parameters. It meaningfully explains what the query string is matched against, but leaves limit (default 20) and the matching mode (substring vs full-text, ranking) entirely undocumented.

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 (Search) and resource (Learnosity integration skills) and enumerates the fields that are matched (id, title, goal, APIs, body content). It is distinguishable from skills_list and skills_read by being retrieval-by-query, though it never names those siblings explicitly.

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?

Usage is only implied: an agent can infer this is the lookup path when it has keywords rather than an id, but nothing states when to prefer skills_list or skills_read instead, nor any prerequisites. No exclusions or alternatives are given.

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