Cohort keeps a coach or course creator’s approved curriculum, promises, module outcomes, and facts that must not be contradicted, then lets an assistant read that curriculum before it answers. A 14-day trial, then Pro. The price is only at checkout.
Glama couldn't complete the latest health check. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 12 tools
The four record_* and two list_* tools are clearly distinct, but the retrieval cluster (get_curriculum_context, curriculum_audit, search_curriculum, get_curriculum_history) all pull overlapping locked facts, distinguished mainly by subtle use-case descriptions rather than different resources. An agent could plausibly reach for the wrong retrieval tool when trying to fetch promises/outcomes/rules.
Most tools follow a verb_noun pattern (get_*, list_*, create_*, record_*, revise_*, search_*), which is predictable and readable. The single deviation is curriculum_audit, a bare noun phrase that doesn't match the verb-first convention.
12 tools is well within a reasonable range and each maps to a distinct curriculum lifecycle concern (programs, modules, promises, outcomes, rules, revisions). There is mild redundancy in the four retrieval tools, but nothing excessive.
The surface covers create, read, update (via revise_approved_fact), search, and audit across programs, modules, promises, outcomes, and rules, which is solid lifecycle coverage. The notable gap is deletion/archival of programs or modules, though the locked-fact model may make that intentional.
Create a new private curriculum program when the user asks. Does not save promises, outcomes, or rules.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds the useful scope constraint that promises/outcomes/rules are out of scope and that the program is private, but it says nothing about duplicate handling (relevant since idempotentHint=false) or required permissions.
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 padding, and the core action is front-loaded. The trailing scope exclusion is slightly abrupt but earns its place as the only routing hint.
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, and the tool is structurally simple with 2 flat params. Still, for a creation tool the description omits any indication of what a program contains or how name/description are used, leaving the agent to guess at invocation content.
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 both parameters, so the description carries the full burden and fails it: neither "name" nor "description" is mentioned, and their constraints (1-200 chars, 5000 chars) live only in the schema. An agent gets no semantic guidance on what belongs in the description field versus the program name.
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 ("Create a new private curriculum program") and the qualifier "private" adds a distinguishing attribute. It is clearly separable from list_programs and the record_* siblings, though it never names them directly.
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?
"when the user asks" is a vague trigger that gives no real conditions. The exclusion "Does not save promises, outcomes, or rules" does route the agent away from record_promise / record_module_outcome / record_noncontradiction_rule, which is useful, but those alternatives are never named and no prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve locked promises, module outcomes, and non-contradiction rules so the assistant can compare them with a short proposed lesson or answer. This tool supplies evidence; the assistant must identify contradictions. Does not save or approve anything.
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No | ||
| programId | Yes | ||
| proposedText | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond that by defining the division of labor (tool supplies evidence, assistant detects contradictions) and restating the non-mutation guarantee for emphasis ('Does not save or approve anything').
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 what is retrieved, followed by the usage contract and the negative guarantee. Every sentence carries information, though the second and third sentences could be merged with no loss.
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 described, and annotations plus the description together give a complete behavioral picture. The remaining gap is parameter-level detail, which is minor for a small read tool whose arguments are largely self-explanatory.
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 full burden, and it only implicitly touches one parameter via 'short proposed lesson or answer' (proposedText). Neither programId nor offset is explained, and no format, UUID, or pagination semantics are conveyed.
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 (retrieve) and enumerates the exact resources it returns: locked promises, module outcomes, and non-contradiction rules. This is well above a tautology and separates it from mutation siblings like record_promise or revise_approved_fact, though it never names the read-side siblings (search_curriculum, get_curriculum_context) it most resembles.
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 triggering condition clearly ('so the assistant can compare them with a short proposed lesson or answer') and assigns responsibility ('the assistant must identify contradictions'). It does not, however, explicitly say when to prefer this over search_curriculum or get_curriculum_context, so the routing is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the approved curriculum before answering a learner or drafting a lesson. request is a brief topic query, never a chat transcript. Results are a selection; use search_curriculum for a specific missing fact. Locked facts must not be contradicted.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| request | Yes | ||
| programId | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new traits beyond that: results are a selection (not exhaustive), and locked facts returned must not be contradicted. It omits pagination/limit behavior, which is minor.
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?
Four short sentences, front-loaded with the primary action, and every sentence carries distinct information (purpose, param constraint, alternative routing, output constraint). No 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?
An output schema exists, so return-value explanation is rightly omitted, and annotations carry the safety profile. The remaining gap is only minor param-level detail (programId, limit semantics) for an otherwise complete routing-and-constraint picture.
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% across three parameters, so the description must compensate and only partly does. It adds real meaning for 'request' ('a brief topic query, never a chat transcript'), but programId and limit are left entirely undocumented in both schema and prose.
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?
Specific verb + resource ('Retrieve the approved curriculum') with a stated scope that separates it from siblings. It explicitly contrasts itself with search_curriculum, 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?
States the triggering context ('before answering a learner or drafting a lesson') and names the alternative plus the condition that selects it ('use search_curriculum for a specific missing fact'). When-to-use and when-to-use-something-else are both explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read previous and new content for a saved curriculum entry, newest first. No changes are made.
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No | ||
| curriculumEntryId | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'No changes are made' is largely redundant. The description does add genuinely new behavioral context with the 'newest first' ordering, but it says nothing about pagination behavior despite the offset parameter.
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, front-loaded with the resource and ordering. The closing 'No changes are made' earns little because the annotations already assert it, so the description is efficient but slightly padded.
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 read-only nature is covered. However, for a tool with an offset parameter the absence of any pagination or paging guidance leaves a real gap for an agent that must fetch long histories.
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% and the description names neither parameter. curriculumEntryId's role is inferable from the tool name, but the offset parameter and its pagination semantics are entirely undocumented in both the schema and the description, so the description fails to compensate for the coverage gap.
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 ('Read') and resource ('previous and new content for a saved curriculum entry') plus ordering ('newest first'), which is enough to separate it from get_curriculum_context and curriculum_audit. It stops short of naming the siblings it should be chosen over, so it is clear but not fully differentiated.
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 for inspecting the change history of one entry, but the description never states when to prefer it over get_curriculum_context, curriculum_audit, or search_curriculum. No prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read module records in teaching order. Page with offset to inspect older modules or verify a module number before saving.
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No | ||
| programId | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are ordered by teaching sequence and are paged via offset, which tells the agent how to traverse the collection. Return payload shape is left to 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?
Two short sentences, zero padding, and the core action plus the paging instruction are front-loaded. Every clause earns its place.
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 simple read-only list tool with an output schema (so return values need no explanation), the entry is mostly sufficient, but the unexplained required programId and the absence of any note on page size or termination of pagination leave gaps given 0% schema description coverage.
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 parameter meaning, and it only partially does. It clarifies the purpose of 'offset' (paging into older modules), but the required 'programId' UUID is never mentioned, leaving the caller unaware that results are scoped to a single program.
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 module records') plus a meaningful scope detail ('in teaching order'), which an agent can act on. It implicitly separates itself from the write-side sibling record_module via 'before saving', but never names an alternative explicitly, so it falls 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?
Gives real usage context: paginate with offset to inspect older modules, or read to verify a module number before saving (i.e., before calling record_module). There is no explicit 'when not to use' or named alternative, so it is clear context rather than full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the user’s saved curriculum programs before answering or editing. Use the returned ID; do not guess programs. Page with offset.
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only paging behavior ("Page with offset") and the do-not-guess caution; it says nothing about result ordering, page size, or total counts.
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 with no filler, and the highest-value instruction (find the user's programs before acting) is front-loaded. Could be marginally tighter by merging the ID caution with the paging sentence, but nothing is wasted.
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 that returns structured data covered by an output schema, the description supplies the essential context: when to call it, how to page, and how to use the returned IDs. Minor gap is lack of guidance on how offset interacts with result volume.
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 the single offset parameter, so the description must carry meaning: "Page with offset" is the only hint it gives. It conveys the pagination intent but not page-size semantics, what offset counts, or how to detect the end of the 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+resource: retrieving the user's saved curriculum programs, with the scope word "saved" narrowing it. It reads slightly as a lookup ("Find") rather than a paged list, but the intent is unambiguous and distinguishable from sibling reads like search_curriculum or get_curriculum_context.
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 clear timing guidance ("before answering or editing") and an operational rule ("Use the returned ID; do not guess programs"), which is exactly the workflow context an agent needs. It does not name an alternative tool or a when-not condition, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a module the owner has approved: its number, title, summary, and the outcome it serves. An occupied module number is preserved unless replaceExisting is true and the owner requested replacement. Identical retries return the saved module. This does not by itself lock a module outcome.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| summary | Yes | ||
| programId | Yes | ||
| moduleNumber | Yes | ||
| outcomeTitle | No | ||
| replaceExisting | No |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations supplied (idempotentHint, destructiveHint, readOnlyHint=false), the description usefully adds the collision/overwrite rule for an occupied module number and the idempotent-retry behavior. It also clarifies scope by noting it does not lock an outcome. It omits bit-for-bit why it's destructive and what errors arise, but the added context is well above the annotation baseline.
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 tight sentences, front-loaded with the core action, then the collision rule, then the retry/scope caveats. Every sentence carries new information and there is no 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?
For a create/upsert mutation with annotations and an output schema present, the description covers the key behavioral edge cases (occupied number, retry idempotency, no outcome lock). It doesn't discuss validation errors, permission requirements, or the output shape, but the output schema presumably handles the latter.
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 the load, and it names module number, title, summary, and outcome. It also explains replaceExisting's meaning (allow overwrite of an occupied number). It does not clarify programId's role or that outcomeTitle is a separate field from the required summary/title.
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 clear verb (Store) and resource (a module) and enumerates the payload fields (number, title, summary, outcome it serves), which distinguishes it from sibling tools like record_module_outcome and list_modules. It doesn't explicitly name a sibling to route away from, but the purpose is 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?
The description implies usage — this is for persisting an owner-approved module — but gives no explicit when-to-use vs when-not guidance and doesn't reference any sibling tool as an alternative. The implicit 'owner-approved' condition is the only usage signal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save what a module must leave the learner able to do, only after the owner approves it. An existing locked outcome stays locked until the owner revises it. Existing entries require expectedRevision. Identical retries leave history unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| title | Yes | ||
| status | Yes | ||
| content | Yes | ||
| programId | Yes | ||
| revisionReason | No | ||
| expectedRevision | No |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real nuance: locked outcomes remain locked until owner revision, existing entries require expectedRevision (optimistic concurrency), and identical retries leave history unchanged. These go beyond what the structured annotations convey, though auth/permission requirements are still implicit.
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?
Four dense sentences, no filler, with the approval precondition and locking rule front-loaded before the concurrency and idempotency notes. Efficient and well-ordered, though the opening sentence packs multiple clauses.
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 described. For a 7-parameter mutation with 0% schema coverage, the description covers the critical safety/state behaviors (approval gate, lock, expectedRevision, idempotency) but leaves the semantics of most input fields and the status enum unexplained.
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% across 7 parameters, so the description carries the full burden. It explains expectedRevision and touches on status ('locked'), but says nothing about programId, title, content, tags, revisionReason, or the meaning of the status enum values (LOCKED/DEVELOPING/UNKNOWN/RETIRED), leaving most parameters uninterpreted.
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 ('Save') and resource ('what a module must leave the learner able to do'), making it clear this records a module-level learning outcome. It does not explicitly distinguish itself from the very similar sibling record_module, but the scope wording differentiates it reasonably well.
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 one concrete precondition ('only after the owner approves it') and a state rule for locked outcomes, which is useful implied guidance. However, it never states when to prefer this over record_module or the other record_* siblings, leaving the agent to infer the choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a fact the curriculum must not contradict, only after the owner approves it. Locked rules stay locked until the owner revises them. Existing entries require expectedRevision. Identical retries leave history unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| title | Yes | ||
| status | Yes | ||
| content | Yes | ||
| programId | Yes | ||
| revisionReason | No | ||
| expectedRevision | No |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real context beyond them: the owner-approval prerequisite, the immutability of locked rules, and the concurrency requirement that existing entries need expectedRevision. It does not explain what a write actually destroys or overwrites.
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?
Four front-loaded sentences, each doing distinct work: purpose, locking, concurrency, idempotency. No filler, though the density is high for a compact paragraph.
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 described, and the write semantics, approval gate, and idempotency are covered. However, for a 7-parameter mutation, the meaning of the status enum values and the remaining parameters is unexplained, leaving gaps an agent must resolve from the schema 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 description coverage is 0%, so the description carries the full burden, yet it only clarifies one of seven parameters (expectedRevision is required for existing entries). The status enum, programId, title, content, tags, and revisionReason are left entirely 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: 'Save a fact the curriculum must not contradict,' which is more informative than the bare name 'record_noncontradiction_rule.' It implies a distinction from revise_approved_fact (locked rules until owner revises) but never names that sibling 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?
Provides a clear gating condition ('only after the owner approves it') and a state rule ('Locked rules stay locked until the owner revises them'). It stops short of explicitly naming revise_approved_fact as the alternative when a locked rule must change, so routing to the sibling is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a learner-facing promise only after the owner approves it. LOCKED means the promise is established. An existing locked promise cannot be changed here; the owner revises it with revise_approved_fact. Existing entries require expectedRevision from retrieval. Identical retries leave history unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| title | Yes | ||
| status | Yes | ||
| content | Yes | ||
| programId | Yes | ||
| revisionReason | No | ||
| expectedRevision | No |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare write, destructive, and idempotent hints; the description adds semantics on top: LOCKED means 'established', locked entries are immutable here, and 'Identical retries leave history unchanged' explains the idempotency nuance. It does not explain what a destructive overwrite of a non-locked existing entry actually does, so it stops short of full disclosure.
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?
Four dense sentences, front-loaded with purpose and precondition before the immutability and revision rules. Every clause carries information, though the state-model sentences could be ordered slightly more cleanly.
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 described, and the description covers the approval, locking, and revision-conflict behavior well. The remaining gap is parameter-level detail, which the near-empty schema descriptions fail to backstop.
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% across 7 parameters, so the description must carry parameter meaning, yet it only clarifies status (explaining just the LOCKED value of four) and expectedRevision (must come from retrieval). title, content, tags, programId, and revisionReason are left 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?
The description opens with a specific verb+resource ('Save a learner-facing promise') and immediately scopes it with a precondition ('only after the owner approves it'). It explicitly distinguishes itself from the sibling revise_approved_fact, so an agent can route between them 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?
It states when to use it (after owner approval), when not to (locked promises cannot be changed here), and names the alternative tool (revise_approved_fact) with the condition that selects it. The expectedRevision requirement for existing entries is also given as a usage rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Owner revision of an existing promise, module outcome, or non-contradiction rule, including a LOCKED fact. Preserve the existing title and kind. Requires expectedRevision from retrieval. Conflicting edits fail without overwriting. Identical retries leave history unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| tags | No | ||
| title | Yes | ||
| status | Yes | ||
| content | Yes | ||
| programId | Yes | ||
| revisionReason | Yes | ||
| expectedRevision | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare mutation, destructiveness and idempotency, but the description adds genuinely new behavior: revisions are allowed on LOCKED facts, concurrent/conflicting edits fail rather than overwrite (optimistic concurrency), title and kind are preserved, and identical retries are no-ops on history. It stops short of stating what happens to the prior revision or what permissions 'Owner' entails.
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?
Five short clauses, front-loaded with the action and resource, then invariants, then preconditions and concurrency semantics. No filler; every sentence carries a distinct constraint.
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 described, and the annotations cover the safety profile; the description adds prerequisites, concurrency failure mode and idempotent-retry behavior. Remaining gaps are the untouched parameters (content, revisionReason, tags) and status-transition semantics, which an agent would need for a 7-required-parameter call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 8 parameters, so the description carries the burden, and it clarifies expectedRevision's source ('from retrieval') and the invariant on title/kind. It says nothing about programId, content, revisionReason, tags, or what the status enum values mean, leaving half the parameters undocumented 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?
States a specific verb (revise) plus the exact resource set, enumerating 'promise, module outcome, or non-contradiction rule' which maps directly to the schema's kind enum. This cleanly separates it from the sibling record_promise / record_module_outcome / record_noncontradiction_rule creation tools without needing to open 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?
Gives a clear prerequisite ('Requires expectedRevision from retrieval') and a scope condition ('including a LOCKED fact'), implying retrieval must precede revision. It does not, however, explicitly name the retrieval tool (e.g. get_curriculum_context) or state when to revise vs. re-record, so the routing guidance stops short of fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search saved promises, module outcomes, and non-contradiction rules by literal title or content, or browse every entry with an empty query and offset. Use to verify a fact before revising it.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| offset | No | ||
| programId | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds two non-obvious behaviors beyond the schema: matching is literal on title/content rather than fuzzy, and an empty query combined with offset turns the call into a full browse. Result limits and pagination bounds are still unspecified.
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, zero filler. The resource list comes first and the routing instruction is front-loaded at the end where an agent will act on it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need no explanation, and annotations cover the safety profile. What remains thin is the required programId scoping and any indication of result-set size, which leaves a small but real gap for a paginated search 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 description coverage is 0%, so the description must carry the parameters. It clarifies query semantics (literal match, empty means browse) and implies offset's role in browsing, but says nothing about programId being the required scoping key, nor about the 200-character query cap or offset ceiling.
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 names a specific verb (search) and enumerates the exact resource set: saved promises, module outcomes, and non-contradiction rules. That distinguishes it from the record_* writers, though it does not explicitly differentiate it from read siblings like get_curriculum_context or list_modules.
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 a concrete use case tied to a sibling workflow: 'Use to verify a fact before revising it,' which routes the agent here ahead of revise_approved_fact. It also explains the browse case via an empty query, but offers no when-not guidance or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
create_programcurriculum_auditget_curriculum_contextget_curriculum_historylist_moduleslist_programsrecord_modulerecord_module_outcomerecord_noncontradiction_rulerecord_promiserevise_approved_factsearch_curriculum
Add one secure layer between your agents and this server.